Loam is free and open source for macOS. Your notes stay plain Markdown files on your disk. Download for macOS.[Download for macOS.]
All pages

Agents and CLI

Loam CLI

.md

Install the loam command line, choose a vault, run any app command, and read its output and exit codes.

loam is the command line of Loam, the Markdown notebook for macOS. Every action of the app is a command, so you can script anything you do in the window, or hand it to an agent such as Claude Code or Codex. It works on the plain Markdown folder that is your vault, on this Mac.

Install

The install command puts Loam.app in /Applications and links its command line into ~/.local/bin/loam. Check it:

loam help
Use the app’s own command line for plugins, because it matches the app’s SDK. It lives at Loam.app/Contents/Helpers/loam. If loam is not found, Settings > Developers in the app can put it on your PATH. To build the app and its command line from source, run make app, then use App/build/Loam.app/Contents/Helpers/loam.
Vault commands work without the app open. Only loam app … needs Loam open on that vault.

Choose a vault

A vault is a plain folder of Markdown notes. loam finds it in this order:

  1. The --vault <folder> option.
  2. The LOAM_VAULT environment variable.
  3. The current folder.
# Explicit
loam --vault ~/Notes daily.path

# Or set it once for the terminal
export LOAM_VAULT=~/Notes
loam daily.path

Run commands

loam list prints every command as JSON, with its id, title and summary. Run a command with loam <command> key=value. Quote a value that has spaces.

CommandWhat it does
loam listEvery command, as JSON.
loam helpThe usage text.
loam <command> key=value …Runs a command. Its result goes to stdout.
loam guide [topic]How to use Loam and build plugins. Topics: notes, commands, plugins, ui, test, app, share.
loam skillinstall, uninstall, status or print the agent skill. print shows its text.

A key that a command does not know is ignored, with no error, so check the spelling in loam list. Search takes q=: query= alone fails with a missing argument. Common tasks:

# Full-text search
loam search.content q="roadmap"

# Today’s daily note
loam daily.append text="Met Bob about the beta"
loam daily.path

# Add a task, then list the open ones
loam tasks.add path="Projects/Beta.md" text="Ship the beta 📅 2026-11-02 !high"
loam tasks.list done=false

# Notes that link to a note
loam notes.backlinks path="Projects/Beta.md"

# Tick a habit for today
loam habits.check name="Running"

Backlinks count standard Markdown links, such as [Beta](Projects/Beta.md), not [[wikilinks]].

Output and exit codes

Results go to stdout, usually as JSON. A few commands print plain text: daily.append prints the path of the daily note. Errors go to stderr as a JSON object with an error key:

{
  "error" : "missing argument \"q\""
}
Exit codeMeaning
0Success.
1The command failed, a required argument is missing, or the app refused the request (loam app).
2Bad usage: an unknown command, an argument that is not key=value, or a vault folder that does not exist.

Plugins and the open app

Every feature of Loam is a plugin. The loam plugin commands build, install, update and switch the plugins of your vault. A plugin from the vault lives in .loam/plugins/<id>/, and it stays off until you enable it.

CommandWhat it does
loam plugin new <id> [--ui]Creates a plugin package to edit. --ui adds a panel.
loam plugin build <id> or --allCompiles it into .loam/cache/plugins/. Takes minutes.
loam plugin test <id>Runs its tests against the app’s SDK.
loam plugin install <url>Clones a git URL, or copies a folder, and builds it. Never enables it.
loam plugin install --catalog <id>Installs a plugin of the public catalog, pinned to its commit.
loam plugin catalog [query]Lists the plugins of the public catalog.
loam plugin outdatedLists the plugins with a newer version. Needs the network.
loam plugin update <id> or --allUpdates and rebuilds. A plugin that asks for new permissions is disabled until you enable it again.
loam plugin rollback <id>Goes back to the version the last update replaced.
loam plugin listLists every plugin, as JSON.
loam plugin enable <id> or disable <id>Turns a plugin on or off.
loam plugin remove <id>Moves it to .trash/plugins/ and turns it off.
Read a plugin’s permissions before you run loam plugin enable. See Plugin permissions.

loam app talks to the Loam window that has the vault open. Without --vault, it uses LOAM_VAULT, then the vault around the current folder, then the last vault the app opened.

CommandWhat it does
loam app infoThe open vault and note.
loam app listThe window’s commands, UI ones included, as JSON.
loam app open <path>Opens a note in the window.
loam app run <command> [key=value …]Runs a command inside the app, for window commands such as themes.use.
loam app shot <file.png>Saves a picture of the window.
loam app relaunchRestarts the app on the vault, to load rebuilt plugins.

When the app is not running on that vault, loam app exits with code 1 and tells you to open it.

For AI agents

An agent needs no prior knowledge of Loam. Install the skill, and the agent reads loam guide before it touches a vault. See Agents for the full setup and rules.

loam skill install
loam skill status
FlagAgents and folder
--claudeClaude Code, OpenCode: ~/.claude/skills/loam/
--codexCodex: ~/.codex/skills/loam/
--agentsAntigravity, Pi, OpenCode, Codex: ~/.agents/skills/loam/

Without a flag, every target is written.