inkentry CLI reference

Every command accepts -c, --config <path> to override the default config file (~/.config/inkentry/config.toml) and --color <auto|always|never> (default auto, on when stdout is a terminal and NO_COLOR is unset). The flags and defaults below match the installed binary; run inkentry <command> --help to confirm against your version.

A local inkentry-server is auto-started on demand and provides embeddings (native, via the candle-served F2LLM-v2-330M model) and, when a chat endpoint is configured, LLM inference. Commands that need semantic search or an LLM (search in semantic or auto mode, harvest) use that server; the always-available commands (graph, text and ast-grep search, memory add/list, context) work with no server.

Core commands

inkentry init

Initialise inkentry for the current project: register it, parse and chunk the source tree, start the local server if needed, and embed the code.

inkentry init [options]

cd /path/to/project
inkentry init
inkentry init --hook            # also wire up auto-index/harvest on commit
inkentry init --name acme/tools # explicit slug (e.g. no git remote)

inkentry index

Index a codebase directory.

inkentry index <path> [options]

A plain inkentry index (no --force) re-indexes changed files (blake3 hash) and also backfills embeddings for any already-parsed chunk that has no embedding yet, for example if a previous run parsed the tree before the embedder had finished loading. Each batch is written to the database as soon as it completes, so an interrupted run never loses already-embedded chunks: re-run inkentry index to pick up where it left off.

Add a .inkentryignore file (same syntax as .gitignore) to any directory to exclude files from indexing. It takes higher precedence than .gitignore.

inkentry index ./myproject
inkentry index ./myproject --force --batch-size 16

inkentry search

Search the index. In auto mode (the default) inkentry uses semantic/hybrid search when an index and server are available and falls back to ast-grep otherwise, printing warm-up and coverage notices on stderr as it does.

inkentry search <query> [options]

semantic/hybrid uses LinearRAG: a two-stage entity-activation and personalised PageRank pipeline that improves multi-hop recall over raw KNN. text and ast-grep need no embedding model or server. An explicit semantic/hybrid against a warming or empty index returns an actionable error rather than an empty result set.

inkentry search "where is the JWT token validated"
inkentry search "database schema migration" --limit 5 --format json
inkentry search "authentication middleware" --graph
inkentry search "TODO fix me" --mode text          # FTS only, no server needed
inkentry search "$X.unwrap()" --mode ast-grep      # structural live search (metavariable)

inkentry status

Show indexing statistics for the current project (or all projects).

inkentry status [options]

When chunks outnumber embeddings, inkentry status prints an "Embedding in progress" line showing the embedded/total count. In local_first mode it also reports pending and last-synced memory counts.

inkentry status
inkentry status --all --format json

inkentry context

Print agent session context: other live sessions, handoffs, open questions, decisions, requirements, and (when an index is available) extracted conventions. This is the recommended place for an agent to start a session.

inkentry context [options]

Under a tight --budget, durable memory (decisions and requirements) is kept ahead of ephemeral open questions when trimming to fit; the section display order is unchanged.

When projects are linked with inkentry link, context also surfaces locked or cross-project-tagged decision and requirement entries from linked projects' memory stores, each labelled with its source project. Pass --local-only to suppress this. See the memory guide.

inkentry context
inkentry context --kind decision
inkentry context --local-only      # primary project only, no dep pass
inkentry context --budget 4000     # cap total output at ~4000 tokens
AGENT=true inkentry context        # JSON for machine processing

inkentry graph

Query the code graph: imports, function calls, class inheritance.

inkentry graph <symbol> [options]

inkentry graph RagPipeline
inkentry graph src/storage/db.rs --kind imports
inkentry graph validate_token --live

inkentry chunks

Show the raw indexed chunks for a file. Useful for debugging or providing precise context to an agent.

inkentry chunks <path> [options]

inkentry chunks src/indexer/parser.rs
inkentry chunks src/indexer/parser.rs --format json

inkentry languages

List all supported languages and their tree-sitter parsers.

inkentry languages

inkentry link / inkentry unlink / inkentry links

Add or remove a project dependency. When linked, inkentry search also queries the linked project's index, and inkentry memory search/list/context surfaces locked/cross-project-tagged decisions and requirements from the linked project's memory store. inkentry links inspects existing links.

inkentry link <path>
inkentry unlink <path>
inkentry links list      # list all linked projects with status
inkentry links check     # exit 1 if any linked index is stale or missing

inkentry link ../shared-utils       # search this project and shared-utils together
inkentry links list

inkentry autoclean

Remove registry entries for projects whose root path no longer exists on disk.

inkentry autoclean

Memory commands

inkentry memory add --title "..." [--body "..."] [--kind decision] [--tags auth,db] [--files src/auth.rs]
inkentry memory add --from-url <url> [--title "override"] [--kind requirement]
inkentry memory add --title "..." --kind decision --supersedes <old-id>   # new entry + supersedes edge
inkentry memory search <query> [--limit 10] [--mode hybrid] [--as-of <date>] [--expand-graph] [--local-only]
inkentry memory list [--kind decision] [--limit 20] [--archived] [--source-ref <sha>] [--as-of <date>] [--local-only]
inkentry memory show <id> [--format text|json]
inkentry memory supersede <old-id> <new-id>  # archive old, link a supersedes edge to new
inkentry memory timeline <topic> [--limit 20]
inkentry memory graph <id>                    # relationship edges for an entry
inkentry memory failures                      # list all antipatterns
inkentry memory archive <id>
inkentry memory sync [--project <slug>] [--include-archived]  # two-way (see inkentry sync)
inkentry memory reconcile [--dry-run] [--all-projects] [--source-db <path>]
inkentry memory reindex [--dry-run] [--force]  # backfill missing local embeddings
inkentry memory dedupe [--dry-run]             # collapse duplicate entries in memory.db

All memory subcommands accept --backend sqlite|git-notes (default sqlite) and --db <path>.

memory search and memory list accept --local-only to skip the cross-project dep pass. Results from linked projects carry a [from: <project>] badge in text output and source_project / source_project_path fields in JSON.

Memory kinds: decision · context · requirement · note (default) · question · answer · handoff · intent · antipattern

inkentry memory failures is a shortcut for inkentry memory list --kind antipattern.

Supersede takes two ids. inkentry memory supersede <old-id> <new-id> links two entries that already exist: it archives <old-id>, sets its invalidation time, and records a supersedes edge to <new-id>. To record the replacement and the edge in one step, add the new entry with --supersedes <old-id> instead.

git-notes write-through: when store_in_git_notes is true (the default), inkentry memory add also appends the entry to refs/notes/inkentry on HEAD, so memory travels with the code. Outside a git repo this is a graceful no-op.

See the memory guide for full documentation of kinds, supersede chains, and harvesting.

inkentry harvest

Capture memory from git history and session logs: a backfill pass over commits, and the continuous per-commit capture the post-commit hook runs. Sends commit messages (or session logs) to the LLM and extracts significant entries. Requires a reachable inkentry-server with a chat endpoint configured.

inkentry harvest [options]

Already-harvested commits are skipped (tracked via a git:<sha> tag). Routine commits ("fix typo", "wip", and so on) are ignored by the LLM.

inkentry harvest
inkentry harvest --git-range v1.0..HEAD
inkentry harvest --source claude-code --confirm

inkentry memory harvest still works as a hidden, deprecated alias for one release; it prints a warning and runs inkentry harvest.

inkentry sync

Two-way sync (shorthand for inkentry memory sync): push your local memory entries to the configured server and pull remote entries into the local memory.db, so a team converges on one shared memory. Code never leaves the machine; only memory does. Requires a configured server_url.

inkentry sync [--project <slug>] [--source <path>] [--include-archived]

For a one-directional transfer, use inkentry plumbing push (local to server) or inkentry plumbing pull (server to local).

Authentication

inkentry auth manages the bearer key for a self-hosted team server; inkentry login / org / logout manage credentials for the hosted inkentry cloud service. The built-in tiers need neither: they run with no server credential at all.

inkentry auth

Manage the per-server bearer credential a self-hosted server_url resolves through, and the credential for a configured LLM endpoint. Distinct from inkentry login, which manages the inkentry cloud token pair.

inkentry auth set-key --server <url>
inkentry auth set-key --llm
inkentry auth list-servers

--server and --llm are mutually exclusive, and exactly one is required. The key is read from stdin if piped, otherwise from an interactive prompt; it is never accepted as a flag value, so it never lands in shell history or ps output.

echo "$SERVER_KEY" | inkentry auth set-key --server https://inkentry.internal.example.com
inkentry auth list-servers

The key is stored in your OS secret store (macOS Keychain, Linux Secret Service, Windows Credential Manager). INKENTRY_SERVER_KEY still works everywhere and takes precedence over the stored key, which is handy for CI.

inkentry login

Authenticate with inkentry cloud using a browser-based device login. inkentry login prints a verification URL and a short user code; open the URL, enter the code, and approve the sign-in in your browser. On success, short-lived tokens are stored in your config and refreshed automatically in the background.

inkentry login [--org <slug>] [--cloud-url <url>]

inkentry login
inkentry login --org acme

Tokens are written to the [auth] table of ~/.config/inkentry/config.toml (file mode 0600). INKENTRY_SERVER_KEY continues to take precedence, which is handy for CI.

inkentry org

Manage the active organisation for an authenticated session.

inkentry org switch <slug|uuid>

inkentry org switch re-scopes your session to another organisation you belong to, reusing the stored credentials. Accepts an org slug or its UUID.

inkentry org switch acme

inkentry logout

Remove stored inkentry cloud credentials. Bare inkentry logout clears only the [auth] token pair written by inkentry login; it does not touch any self-hosted server key, so recovering from a broken cloud login never costs you the keys you use on other projects. Clearing server keys is a separate, explicit action.

inkentry logout [--servers | --server <url>]

inkentry logout
inkentry logout --server https://inkentry.internal.example.com
inkentry logout --servers

Server commands

inkentry server

Manage the local inkentry-server daemon. Runtime state lives under ~/.local/state/inkentry/ (server.pid, server.port, server.log).

inkentry server start [--port <n>] [--bin <path>] [--db <path>] [--llm-url <url>] [--llm-model <name>]
inkentry server stop
inkentry server status
inkentry server logs [-n <lines>]

The LLM endpoint credential is never a server start flag: set it with inkentry auth set-key --llm or INKENTRY_LLM_KEY.

inkentry server start
inkentry server status
inkentry server logs -n 100
inkentry server stop

See server setup for running inkentry-server as a shared team service.

Hooks

inkentry hooks

Manage inkentry's git hooks.

inkentry hooks install [--ci]
inkentry hooks install --pre-push
inkentry hooks uninstall

install writes a post-commit hook that runs inkentry index and inkentry harvest after each commit (both --detach so git is not blocked). --ci prints a GitHub Actions workflow step instead of writing a hook.

install --pre-push writes a pre-push hook that publishes your memory (refs/notes/inkentry) to the remote you push to, so decisions travel with the code they describe. It merges the remote's notes into yours before pushing (a union, so neither side is dropped) and never blocks your push: on failure it warns and exits 0, and it never force-pushes. Publishing is opt-in, so your memory stays local until you install it.

Developers without inkentry installed are unaffected. uninstall removes every hook inkentry installed, leaving any other hooks alone.

Plumbing commands

Low-level commands for agents and scripts. All emit JSONL and exit non-zero on error (exit 1 for "no results", exit 2 for errors).

inkentry plumbing cat-chunks <file>     # indexed chunks for a file
inkentry plumbing ls-files              # all indexed files
inkentry plumbing parse-file <file>     # parse + chunk without storing
inkentry plumbing hash-file <file>      # blake3 hash + index currency
inkentry plumbing knn <query>           # KNN vector search
inkentry plumbing embed                 # read stdin lines, emit vectors
inkentry plumbing graph-edges           # code graph edges
inkentry plumbing read-memory           # memory entries as JSONL
inkentry plumbing push                  # one-way: seed the server from local memory
inkentry plumbing pull                  # one-way: pull server entries into local memory.db
inkentry plumbing publish-notes [remote]  # publish memory notes to a remote (writes + network I/O)

Environment variables

What's next

• Memory guide - kinds, supersede chains, harvesting from git history
• Config reference - all config fields in one place
• Server setup - self-host inkentry-server for your team