CLI reference

hallouminate is a single binary. The CLI, the MCP server, and the daemon are all the same executable; CLI subcommands dial the daemon over a Unix domain socket (see Architecture).

Command	Purpose
`hallouminate serve`	Run the stdio MCP server (auto-spawns the daemon if down).
`hallouminate index [--corpus NAME]`	Bulk (re)index one corpus, or every configured corpus.
`hallouminate ground "<query>" [flags]`	Semantic search from the CLI.
`hallouminate daemon <run\|stop\|restart\|status>`	Manage the long-lived daemon.
`hallouminate config <init\|show\|validate\|download>`	Inspect or scaffold config.
`hallouminate hook <install\|uninstall>`	Manage the per-repo discovery hook.

hallouminate --version prints the version; hallouminate --help and hallouminate <command> --help print usage for any subcommand.

`serve`

hallouminate serve

Starts the stdio MCP server an agent connects to. It is stateless beyond its tool router and a startup-captured working directory — every tool call dials the daemon. If no daemon is running, serve spawns one.

`index`

hallouminate index               # rebuild every configured corpus
hallouminate index --corpus repo:hallouminate:wiki

Use this when files were touched outside hallouminate. Writes that go through add_markdown already auto-reindex just the changed file.

`ground`

hallouminate ground "how does the daemon work"
hallouminate ground "socket protocol" --corpus repo:hallouminate:wiki --format json-pretty

Flag	Effect
`--corpus NAME`	Corpus to search (defaults to the wiki for the current repo).
`--format outline\|json\|json-pretty`	Output shape. `outline` (default) is a ripgrep-style digest.
`--full`	Return full chunk bodies instead of snippets.
`--top-files N`	Number of files to roll up.
`--chunks-per-file N`	Chunks to include per file.
`--limit N`	Hard cap on returned chunks.
`--snippet-chars N`	Snippet length when not using `--full`.

`daemon`

hallouminate daemon run        # run in the foreground
hallouminate daemon status     # is one running?
hallouminate daemon stop
hallouminate daemon restart

The daemon is the single owner of the LanceDB ground directory. Restart it after editing the baseline config; repo-layer edits take effect on the next request without a restart. --config PATH overrides the baseline config path.

`config`

hallouminate config init       # scaffold the XDG baseline config
hallouminate config show       # print the effective merged config for this cwd
hallouminate config validate   # parse + flag unknown top-level keys
hallouminate config download   # pre-fetch the configured embedding model

See Configuration.

`hook`

hallouminate hook install [--repo PATH]
hallouminate hook uninstall [--repo PATH]

Installs or removes a per-repo discovery hook. --repo PATH targets a repo other than the current directory.

Socket override

--socket PATH on index, ground, and the other client subcommands points at a specific daemon socket. Otherwise the socket is resolved from HALLOUMINATE_SOCKET, then $XDG_RUNTIME_DIR, then the cache dir — see Architecture.

Keyboard shortcuts

hallouminate