Command line

Start the Model Context Protocol stdio server, or inspect registered tools.

clearly mcp [serve | tools] [--read-only]

Subcommands

• serve — start the stdio server. Default. Same as clearly mcp.
• tools — print every registered tool's name, description, input schema, and output schema as JSON.

Examples

# Typical Claude Desktop config (claude_desktop_config.json)
"clearly": { "command": "/usr/local/bin/clearly", "args": ["mcp"] }

# List every registered tool
clearly mcp tools | jq -r '.[].name'

# Inspect the read-only-only set
clearly mcp tools --read-only

Full-text search across loaded vaults. Streams NDJSON hits — one per line — ranked by BM25.

clearly search <query> [--limit N]

Operators

Inside the query string, narrow results without changing the schema:

• tag:foo — file must carry tag foo (case-insensitive). Repeat for AND.
• path:notes/sub — file's vault-relative path must start with this prefix (case-insensitive).

Output

One JSON object per line: {vault, vault_path, relative_path, filename, matches_filename, excerpts:[{line_number, context_line}]}.

Examples

clearly search pricing
clearly search "API design" --limit 5 | head -1 | jq .
clearly search rust --limit 20 | jq -r '.relative_path'

# Operators
clearly search "tag:work meeting"
clearly search "path:journal/2026/ tag:idea"
clearly search "tag:open"           # filter-only, no free text

# Wrap NDJSON into a single array
clearly search foo | jq -s '.'

Read a note by vault-relative path, with optional line range. Returns content plus content hash, size, modified timestamp, parsed frontmatter, headings, and tags.

clearly read <path> [--start-line N] [--end-line N] [--in-vault NAME]

Examples

clearly read Daily/2026-04-17.md
clearly read Strategy/pricing.md --start-line 10 --end-line 40
clearly read Inbox/idea.md --in-vault Work | jq -r '.content'

List notes in loaded vault(s). Walks the filesystem fresh every call — results always reflect current on-disk state. Streams NDJSON.

clearly list [--under PREFIX] [--in-vault NAME]

Examples

clearly list
clearly list --under Daily/
clearly list | jq -r '.vault' | sort | uniq -c
clearly list --under Projects/ | jq -r '.relative_path' | xargs -I{} clearly headings {}

Heading outline (H1–H6) for a note: level, text, and 1-based line number.

clearly headings <path> [--in-vault NAME]

Parsed YAML frontmatter as a flat key-value map. Empty map when the note has no frontmatter block.

clearly frontmatter <path> [--in-vault NAME]

Notes that link to a target note via [[wiki-links]], plus “unlinked mentions” — places the target's filename appears as plain text without being wrapped.

clearly backlinks <path> [--in-vault NAME]

No argument: stream {tag, count} records across every vault. With a tag argument: stream every note carrying that tag. Tags come from inline #hashtags and YAML frontmatter tags:.

clearly tags                       # all tags with counts
clearly tags architecture          # all notes tagged #architecture
clearly tags | jq -s 'sort_by(-.count) | .[:20]'

Create a new note. Parent directories created automatically. Fails with exit 5 / note_exists if the path is already taken — use update to modify.

clearly create <path> (--content STR | --from-stdin) [--in-vault NAME]

Examples

clearly create Daily/2026-04-17.md --content "# Today\n\nNotes..."
cat draft.md | clearly create Inbox/draft.md --from-stdin
clearly create Notes/idea.md --content "..." --in-vault Work

Update an existing note in one of three modes. replace overwrites the whole file. append adds to the end. prepend inserts after the YAML frontmatter block (or at the top if there is none).

clearly update <path> --mode replace|append|prepend (--content STR | --from-stdin) \
                [--in-vault NAME] [--expected-content-hash <sha256>]

--expected-content-hash opts into optimistic concurrency — the call returns exit 5 / stale_content if the on-disk file has changed since the supplied hash, so a script can re-read and retry without clobbering a concurrent edit.

Move or rename a note within a vault. Vault-aware: reads every note that links to the source, rewrites those [[wiki-links]] to the new path (preserving heading anchors and aliases), then moves the file and updates the index without losing inbound link relationships.

clearly move <from-path> <to-path> [--in-vault NAME]

Examples

clearly move Inbox/draft.md Notes/published.md
clearly move Inbox/draft.md Archive/2026/draft.md

List loaded vaults as NDJSON: {name, path, file_count, last_indexed_at, bundle_id}. Use status for a single-document diagnostic snapshot. Vault add/remove lives in the app — the CLI subcommands are placeholders that exit 2 and point you to Settings.

clearly vaults                         # same as `clearly vaults list`
clearly vaults list --format text      # namepathfile_count

Vault index maintenance. rebuild performs a full filesystem walk and re-hashes every markdown file — use it after out-of-band file ops or to recover from a corrupted index.

clearly index                        # same as `clearly index rebuild`
clearly index rebuild --in-vault Work

One-shot diagnostic snapshot: binary version, configured bundle id, embedding model version, every loaded vault with file count and last-indexed timestamp. Single JSON document — intended for support tickets and human eyeballing.

clearly status
clearly status | jq '.vault_count'
clearly status --format text