Docs/CLI/solomon CLI reference

solomon CLI reference

solomon is a command-line client for a Solomon vault. It never runs as a server and is never deployed — it's a local binary that runs on your machine.

The three-transport model

The CLI reaches a vault one of three ways, chosen automatically per call:

Loopback bridge — the running desktop app's local MCP server on 127.0.0.1:<port>/mcp. Shares the live Y.Doc, so a CLI write can't diverge from an open editor. Used whenever the target vault is open in the app.
Single-writer core — drives a closed local vault directly, holding a file lock. Used when a local vault isn't open in the app.
Hocuspocus sync peer — for a closed online (synced) vault, joins the sync server as a CRDT peer, same protocol the desktop app uses.

The transport decision is re-run on every call (not cached), which is why solomon actions await can poll for hours across the app opening or closing mid-wait without holding any lock.

The probe distinguishes "app closed" (safe to go direct — local core or sync peer) from "app running but refused" (a bad/cloud-scoped token, or any HTTP/RPC error) — in the refused case the CLI errors loudly rather than silently editing files or racing the app's own sync session, since the app may be serving that exact vault under a live Y.Doc.

Writes follow the presented key's mode: a propose-scoped key (the default) stages a change for review in the app, exactly like any other agent; a force-scoped key applies it immediately. solomon actions is the one exception — it always prefers a force-scoped key when one exists in mcp.json (see Docs/CLI/HITL delegations (actions).md), because the Ops Delegation board only reads the live doc.

Global flags

These apply to every subcommand:

Flag	Env fallback	Meaning
`--token <TOKEN>`	`SOLOMON_MCP_TOKEN`	Bearer token for the loopback bridge. Defaults to the token in the app's `mcp.json` (propose mode). Pass a force-scoped key to apply writes immediately.
`--port <PORT>`	`SOLOMON_MCP_PORT`	Loopback port. Defaults to `mcp.json`'s port, else `8732`.
`--vault <handle\|path>`	—	Target a specific open vault by handle (folder name) or path, when more than one is open (M19 multi-window). Defaults to the app's active vault.
`--sync-url <URL>`	`SOLOMON_SYNC_URL`	Sync server URL for online vaults (transport 3). Defaults to the production server.
`--sync-token <TOKEN>`	`SOLOMON_SYNC_TOKEN`	Bearer token for the sync server. Defaults to the JWT the desktop app cached at sign-in.
`--json` / `-j`	—	Print the raw JSON tool payload instead of the formatted (human-readable) output.

mcp.json lives at <os-data-dir>/app.solomon.editor/mcp.json (macOS: ~/Library/Application Support/…) and is written by the desktop app the first time it runs.

Subcommands (18)

`vaults`

List the vaults open in the running app (handle, path, which is active).

solomon vaults

`search <query>`

Hybrid lexical + semantic search (falls back to plain lexical with no local embedding index). See Docs/Search/Metadata filters.md for the full path:/tag:/has:/[key:value] inline grammar.

Key flags:

--regex — treat query as a case-insensitive regex over title+body (forces the lexical path; disables inline filter-syntax extraction from the pattern itself).
--limit <n> — max hits.
--metadata-only — omit the body snippet from each hit (equivalent to --truncate 0).
--truncate <N> — cap each snippet to at most N chars (CLI-side only; never reaches the tool call), appending … when cut.
--path <PREFIX> — restrict to notes under a folder (segment-aware, e.g. Tasks/). ANDs with any path: term already in the query.
--where <CLAUSE> — a bases where-clause ANDed onto the query, e.g. --where 'status is "active"' (same grammar as solomon base). Not available for online (sync-peer) vaults — that transport has no local evaluator.

solomon search "auth" --where 'status is "active"' --path Tasks/ --metadata-only

`list`

List notes, newest first.

--since-ms <epoch-ms> — only notes modified at/after this timestamp.

solomon list --since-ms 1752000000000

`read <path>`

Read one note by vault-relative path (frontmatter + body; prints a [nearest AGENT.md applies] hint on stderr when one governs the note's directory).

solomon read "Concepts/RLHF.md"

`base <dsl>`

Run a base DSL query. Pass the DSL as one quoted positional arg, --file <path>, or --stdin.

solomon base 'from notes
where status is "active"
sort __modified desc'

`create <path>`

Create a new note. Content via a --content string, --file <path>, or --stdin; defaults to empty.

solomon create "Tasks/New Task.md" --content $'---\nstatus: open\n---\n# New Task\n'

`write <path>`

Overwrite a note's body and/or set frontmatter.

--body <text> / --stdin — full replacement body.
--set KEY=VALUE (repeatable) — frontmatter to patch; value null deletes the key.

At least one of body or --set is required.

solomon write "Tasks/New Task.md" --set status=done --set due=null

`append <path> [text]`

Append text to a note's body (positional text, or --stdin).

--no-newline — don't ensure a leading newline before the appended text.

solomon append "Tasks/New Task.md" "- follow up next week"

`edit-section <path>`

Tactical in-place edit of a section, targeted by a unique --anchor substring (mutually exclusive with --heading) or a --heading.

--op <replace|insert_before|insert_after|append_within> — required. append_within needs --heading.
--text <text> / --stdin — required.

solomon edit-section "Tasks/New Task.md" --heading "## Notes" --op append_within --text "- new detail"

`set-prop <path> KEY=VALUE...`

Set/delete frontmatter properties (one or more key=value args; value null deletes).

solomon set-prop "Tasks/New Task.md" status=done priority=2

`move <from> <to>`

Move/rename a note or folder (preserves the frontmatter id and history).

solomon move "Tasks/New Task.md" "Tasks/Archive/New Task.md"

`delete <path>`

Send a note or folder to the OS trash (recoverable, never a hard unlink). Requires --confirm.

solomon delete "Tasks/Archive/New Task.md" --confirm

`raw <tool> [args]`

Call any MCP tool directly by name (see Docs/MCP/MCP tool surface.md for the full tool list). args is a JSON object string; defaults to {}.

solomon raw note_set_properties '{"rel_path":"Tasks/New Task.md","properties":{"status":"done"}}'

`registry <add|rm|list>`

Manage the vault registry — local paths / online vaults usable when the app is closed. Pure local config, no transport.

registry add <name> --path <dir> or --online <ref> [--default]
registry rm <name>
registry list

solomon registry add work --path ~/vaults/work --default

`actions <post|list|await|resolve>`

The HITL Delegation Actions surface behind the Ops Delegation board. Full reference: Docs/CLI/HITL delegations (actions).md.

solomon actions post --kind question --title "Pick storage" --option R2 --option Railway

`kb <sources|search|read|balance|keys>`

Query paid knowledge bases. search is always free; every kb read bills the KB access key's balance/budget (exit code 4 = out of credit/budget).

Auth: --kb-key/SOLOMON_KB_KEY (search/read/balance); a session token (--session/SOLOMON_SESSION_TOKEN, else --sync-token) for kb keys.
--app-url/SOLOMON_APP_URL — base URL of the Solomon app (defaults to https://app.lomon.dev).
Subcommands: kb sources (list KBs for sale), kb search <query> [--source <slug>] [--limit <n>] (free), kb read <source> [path] [--note-id <id>] (paid), kb balance, kb keys list|mint --name <label> [--budget <$>]|revoke <key_id>.

solomon kb search "vector databases" --source research-corpus
solomon kb read research-corpus --note-id abc123

`export <pdf>`

Headless, offline file export — pure local filesystem, never opens a loopback/core/sync transport. Today just export pdf, rendering a markdown note via the same Typst core the desktop "Export as PDF…" uses.

export pdf <note> [-o/--output <file>] [--title <t>] [--assets-root <dir>] — note is a vault-relative path (resolved against --vault/the default registry vault) or a direct filesystem path.

solomon export pdf "Concepts/RLHF.md" -o ~/Desktop/RLHF.pdf

`local-tag-report <fixture>`

Score local-tagging predictions against a curated golden set (precision/recall/F1 per note + micro/macro aggregate). Offline — no running app or vault needed; speaks the same sidecar protocol as the desktop app's local-tagging engine.

fixture — a JSONL golden-set file ({path, title, body_excerpt, taxonomy, gold_tags}).
--driver <path> / SOLOMON_LOCAL_TAG_DRIVER — the sidecar driver executable. CI points this at a fake driver emitting canned JSON; real accuracy runs (Apple Silicon only) point it at a wrapper execing the provisioned MLX driver.

solomon local-tag-report golden.jsonl --driver ./fake_driver.sh

Guardrails shared with every agent surface

_private/, dot-folders (.solomon/, etc.), and Widgets/ are quarantined from every note-level read/write tool the CLI calls — the same quarantine the local MCP server enforces (see Docs/MCP/MCP tool surface.md). Compose-style edits (write, append, edit-section, set-prop) are markdown-notes only.

[[HITL delegations (actions)]] — full reference for the actions subcommand's post/list/await/resolve flow.
[[MCP tool surface]] — the tool set the loopback transport calls.
[[Metadata filters]] — the inline path:/tag:/[key:value] grammar search --path/--where compiles to.

solomon CLI reference

The three-transport model

Global flags

Subcommands (18)

vaults

search <query>

list

read <path>

base <dsl>

create <path>

write <path>

append <path> [text]

edit-section <path>

set-prop <path> KEY=VALUE...

move <from> <to>

delete <path>

raw <tool> [args]

registry <add|rm|list>

actions <post|list|await|resolve>

kb <sources|search|read|balance|keys>

export <pdf>

local-tag-report <fixture>