Allume CLI

Open Allume and go to Preferences → CLI (⌘, then click the CLI tab). Click Install. macOS will pop the standard admin auth panel — this is expected, because the symlink lands in a protected directory.

This creates a symlink at /usr/local/bin/allume that points at the allume-cli helper binary bundled inside the Allume app. The symlink survives Allume app moves and updates, so you can rely on allume resolving even if you reinstall.

Prefer no symlink? You can skip this step and call the bundled helper directly — the full path looks like /Applications/Allume.app/Contents/MacOS/allume-cli. The exact path depends on where Allume is installed (Mac App Store, Setapp, etc.).

In the same Preferences → CLI tab, flip Enable CLI on. Until this is on, every allume subcommand returns a friendly “CLI disabled” error — the symlink resolves, but the app refuses to answer.

The CLI and the MCP have separate enable toggles. Turning one on does not turn the other on.

Under the Enable CLI toggle, pick an access mode:

• Read-only (default) — allume search, allume list-workspaces, allume board-content, allume card-content, and allume open work; any write subcommand returns an error.
• Read-write — write subcommands (allume note-create, allume card-create, allume board-create, allume card-move, allume delete, etc.) are allowed.

You can flip between modes at any time. There are no per-board controls today — when the CLI is enabled, every workspace and every board in your local Allume is reachable.

Quick sanity check that everything’s wired up:

allume --version
allume list-workspaces
allume search "meeting notes" --limit 5

If the first two work but search returns nothing, you probably have no workspaces yet — open Allume and create a board, then re-run.

The allume command is just a small helper. It speaks to the running Allume Mac app over a sandboxed pipe — the app is what actually answers. If Allume is fully quit, there is nothing on the other end of the pipe and the CLI prints an “Allume not running” error.

You do not need to keep Allume in focus. Foreground or background is fine — as long as it’s in the Dock or running in the background, the CLI works.

Apple does not provide a sandboxed way for the app to remove the symlink it created, so uninstall is a one-line paste in Terminal:

allume cli uninstall

This prints the exact rm command to remove the symlink (it does not run it for you — you stay in control). Paste the printed command, and /usr/local/bin/allume is gone.

You can also flip Enable CLI off in Preferences → CLI without removing the symlink — the binary stays installed but every call returns “CLI disabled”.

# All workspaces
allume list-workspaces

# Search every workspace
allume search "design review"

# Narrow to one workspace, raise the cap
allume search "design review" --workspace <id> --limit 200

# List cards on a board
allume board-content <board-id>

--workspace accepts the id printed by list-workspaces. --limit defaults to 50 and caps at 500.

# Metadata + inline body (for text, url, chain cards)
allume card-content <card-id>

# Stage a PDF / image / file to disk and return its path
allume card-content <card-id> --contents file-uri

# Stream the raw bytes of a PDF card to stdout
allume card-content <card-id> --contents raw > out.pdf

For text-shaped cards (text, url, chain) the body is always inline. For blob-shaped cards (pdf, image, file, video) you pick how bytes are surfaced with --contents.

allume open <board-id>
allume open <card-id>

This jumps Allume’s UI to the target. Handy when a script finds something interesting and you want to dive in by hand.

# Create a new text note in a board
allume note-create --board <board-id> --title "Standup" --body "Notes..."

# Save a URL as a card
allume url-create --board <board-id> --url "https://example.com"

# Create a sub-board
allume board-create --parent <board-id> --title "Sub-project"

All write subcommands return the new document’s id, so you can chain calls in scripts. Switch the workspace to Read-write in Preferences first — write tools refuse with a clear error otherwise.

Every subcommand accepts --format (short flag -f):

• md (default) — a markdown table, human-readable in Terminal.
• json — pretty-printed JSON with sorted keys and ISO-8601 dates. Use this when piping to jq.
• id — bare id(s), one per line. Use this when piping into another allume call.
• plain — tab-separated rows, no header. Use this with cut / awk.

# Find a board, then list its cards
allume search "design" --format id | head -1 \
  | xargs allume board-content --format json | jq '.[].id'

Both are the same allume-cli helper binary bundled inside the Mac app. The difference is who’s driving:

• The MCP is for AI assistants. An AI client (Claude Desktop, Cursor, etc.) spawns allume-cli mcp and talks to it over the Model Context Protocol.
• The CLI is for you and your scripts. You type allume search ... in Terminal, or call it from a shell script.

Each surface has its own enable toggle and its own read-only/read-write switch in Preferences — turning one on does not turn the other on. The two surfaces share the same underlying tools, so anything an AI agent can do, you can do from the CLI.

No. The allume command only talks to the running Allume Mac app on your Mac. Nothing it does sends data over the network on its own.

(If you pipe allume’s output into another tool that calls a cloud service, that’s on you. The CLI itself stays local.)

Turn off Enable CLI in Preferences → CLI. Every allume call immediately returns a “CLI disabled” error. The symlink stays in place so you can flip it back on later without re-installing.

To also block writes while keeping reads working, switch from Read-write back to Read-only.

Yes — every subcommand uses stable exit codes and writes errors to stderr (stdout stays clean so you can pipe it). For long-running or unattended scripts:

• Use --format json and parse with jq instead of scraping the markdown tables. The table layouts are tuned for humans and may change.
• Use --timeout to bound how long a call waits for the Mac app.
• Check for “Allume not running” / “CLI disabled” / “Read-only” errors explicitly — those are user-state conditions, not bugs.

Common causes, in order:

• “Allume not running” or connection failure — the Mac app needs to be open. The CLI is just a proxy.
• “CLI disabled” responses — flip Enable CLI on in Preferences → CLI.
• Write subcommand returns an error — your workspace is in Read-only mode; switch to Read-write in Preferences.
• allume not found in Terminal — the symlink is not installed; use Preferences → CLI → Install, or call the full helper path inside the app bundle.
• Stopped working after an Allume update or move — reinstall the symlink from Preferences → CLI → Install, which re-points it at the current app location.

Still stuck? Email adam@allume.com.