# Loam CLI

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](/docs/install) puts `Loam.app` in `/Applications` and links its command line into `~/.local/bin/loam`. Check it:

```bash
loam help
```

> **Note:** 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`.

> **Note:** 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.

```bash
# 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.

| Command | What it does |
| --- | --- |
| `loam list` | Every command, as JSON. |
| `loam help` | The 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 skill` | `install`, `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:

```bash
# 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:

```json
{
  "error" : "missing argument \"q\""
}
```

| Exit code | Meaning |
| --- | --- |
| 0 | Success. |
| 1 | The command failed, a required argument is missing, or the app refused the request (`loam app`). |
| 2 | Bad 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.

| Command | What it does |
| --- | --- |
| `loam plugin new <id> [--ui]` | Creates a plugin package to edit. `--ui` adds a panel. |
| `loam plugin build <id>` or `--all` | Compiles 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 outdated` | Lists the plugins with a newer version. Needs the network. |
| `loam plugin update <id>` or `--all` | Updates 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 list` | Lists 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. |

> **Note:** Read a plugin’s permissions before you run `loam plugin enable`. See [Plugin permissions](/docs/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.

| Command | What it does |
| --- | --- |
| `loam app info` | The open vault and note. |
| `loam app list` | The 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 relaunch` | Restarts 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](/docs/agents) for the full setup and rules.

```bash
loam skill install
loam skill status
```

| Flag | Agents and folder |
| --- | --- |
| `--claude` | Claude Code, OpenCode: `~/.claude/skills/loam/` |
| `--codex` | Codex: `~/.codex/skills/loam/` |
| `--agents` | Antigravity, Pi, OpenCode, Codex: `~/.agents/skills/loam/` |

Without a flag, every target is written.