CLI Reference

All commands accept -h / --help for full flag list. Source: src/cli/main.c.

Conventions

• Output is JSON unless a --markdown flag is supported.
• Exit codes: 0 OK, 1 I/O error, 2 usage error, 3 daemon returned non-zero.
• GRAFT_PROFILE env selects the active profile; otherwise default.

Write operations

graft insert

Save a node. Idempotent on content hash.

graft insert \
  --title "..." \
  --body  "..." \
  --keywords k1,k2,k3 \
  [--author "..."] \
  [--expires-in 7d] \
  [--supersedes <id_hex>]

Flag	Type	Default	Meaning
--title	string (required)	—	Short headline.
--body	string (required)	—	Full content.
--keywords	csv (required)	—	Comma-separated keyword list (≥1).
--author	string	unset	Provenance tag.
--expires-in	duration	unset	7d, 24h, 30d. Sets expires_at.
--supersedes	id_hex	unset	Atomically replaces the named node.

Returns: { id_hex, duplicate, keyword_edges, semantic_edges }.

graft delete

Hard delete. Cascades to keywords, edges, FTS5, vector table.

graft delete <id_hex>

Read operations

graft query

Verified cache lookup.

graft query "your question text"

Returns STRONG (title + body), WEAK (title only), or MISS (optional fallback list). See Verify & Gating for the gate.

graft retrieve

Hybrid top-k via RRF over (vector cosine, BM25 title, BM25 body).

graft retrieve "your text" [--top-k 25]

graft explore

Keyword-conditioned beam search.

graft explore "your text" \
  [--depth 3] [--beam 4] \
  [--keywords k1,k2]

graft get

Fetch one node by id.

graft get <id_hex> [--markdown]

--markdown emits YAML frontmatter + body, suitable for piping into a file or editor.

graft classify

Suggest 3–6 keywords for a draft title.

graft classify "draft title or text"

Admin operations

graft stats

Runtime metrics + similarity-score percentiles.

graft stats

Returns counts (nodes, edges, keywords) and p25/p50/p75/p90/p95/p99 for insert_topk and query_top1 cosine distributions.

graft consolidate

Safe maintenance.

graft consolidate

Prunes expired nodes, removes orphan edges/keywords, runs ANALYZE, returns a graph-health report.

graft analytics

Stream the usage log with a time window.

graft analytics [--since 7d|24h|30d]

Source: ~/.graft/usage.jsonl. Read-only.

Profile management

graft profile list
graft profile current
graft profile add <name>
graft profile remove <name>
graft profile import <name> --from <path.db>
graft profile export <name> --to   <path.db>
graft profile merge  <src> <dst>
graft profile remote sync --url <path-to-remote.db>

See Profiles for the semantics. Note: remote sync accepts only SQLite file paths in this build; HTTP remote sync is a roadmap item.

Setup helpers

graft setup

One-shot skills installer for an AI assistant.

graft setup claudecode   # ~/.claude/skills/
graft setup codex        # ~/.codex/skills/
graft setup opencode     # ~/.config/opencode/skills/

graft setup does not install hooks and does not modify agent settings, hooks.json, config.toml, or AGENTS.md. See Integrations for manual hook and project-instruction wiring.

graft view

Open the 3D viewer. Auto-builds the SPA on first run, opens http://127.0.0.1:9977/ in your browser. See Viewer.

graft upgrade

In-place self-update from the latest GitHub Release.

graft upgrade [--yes]

Daemon (advanced)

You normally don't run graftd by hand. The CLI spawns it on demand. If you want to inspect:

graftd --config ~/.graft/config.yaml --foreground