hSUM / docs 0.1.0-alpha.4 / cli reference

CLI reference

The complete alpha.4 command surface. Later release-train commands do not appear as stubs.

Global options

Accepted by every command:

Flag	Effect
`-v, --verbose...`	Increase diagnostic detail; repeat for more
`-q, --quiet`	Suppress progress, preserve errors and results
`--no-progress`	Disable progress, keep warnings and summaries
`--no-color`	Disable colored output
`--config <PATH>`	Use an explicit configuration file
`--data-dir <PATH>`	Override the managed data directory
`--cache-dir <PATH>`	Override the managed cache directory

init

Create one local filesystem-backed index and project.

hsum init [OPTIONS] [PATH]

Flag	Effect
`--index <NAME>`	Collision-safe logical index name
`--project <NAME>`	Collision-safe logical project name
`--rebuild`	Replace the trusted index for this root and re-ingest from scratch
`--no-ingest`	Create config and trust state without the first ingest
`--dry-run`	Inspect selection and estimates without writing
`--write-pointer`	Write the optional repository pointer
`--force-pointer`	Replace a conflicting repository pointer
`--allow-broad-root`	Confirm a normally refused broad root
`--allow-large-source`	Confirm a source above default limits
`--index-quota-bytes <BYTES>`	Max managed index bytes, including recovery reserve

trust

Authorize a canonical repository root for direct and MCP use.

hsum trust <PATH> --confirm

--confirm is mandatory. Optional: --index <NAME>, --project <NAME>.

ingest

Refresh the filesystem source into one atomic generation.

hsum ingest [OPTIONS]

Flag	Effect
`--dry-run`	Discover, validate, estimate — commit nothing
`--lock-timeout-ms <MS>`	Max wait for the single-writer lock (default `5000`)
`--allow-empty-snapshot`	Confirm replacing a nonempty source with an empty one
`--allow-mass-delete`	Confirm a deletion above the mass-delete budget

search

Search exact identifiers, conservative quotes, and active lexical text.

hsum search <QUERY> [OPTIONS]

Flag	Effect
`--mode <MODE>`	`auto` or `lexical` (equivalent in alpha.4)
`--limit <N>`	Max passages (default `10`)
`--cursor <VALUE>`	Continue a stable, scope-bound result page
`--timeout-ms <MS>`	Retrieval deadline (default `3000`)
`--json`	Emit exactly one JSON document
`--explain`	Include retriever scoring and stop information

get

Resolve immutable bytes from an hsum://v1 citation.

hsum get <CITATION_URI> [OPTIONS]

Flag	Effect
`--max-bytes <N>`	Max returned UTF-8 bytes (default `16384`)
`--verify-source-hash`	Probe the current source hash against the pinned revision
`--json`	Emit exactly one JSON document

Quote the citation — it contains ? and #.

status, doctor, context

Command	Purpose
`hsum status [--problems] [--json]`	Index state, generation, counts, disk budget
`hsum doctor`	Read-only diagnosis; no repair switches by design
`hsum context [--json]`	Effective index, project, root, binding, config origins

client

hsum client config <CLIENT> [--format json|toml]
hsum client doctor <CLIENT>

Clients: codex, claude-code, claude-desktop, generic. See Connect an agent.

integration

hsum integration install codex --activate <PATH> --confirm
hsum integration status codex [--json]
hsum integration repair codex --confirm
hsum integration uninstall codex --confirm
hsum integration authorize-workspace codex --path <PATH> --confirm
hsum integration revoke-workspace codex --path <PATH> --confirm

Manages the single user-wide Codex registration, bounded agent policy, exact repository activation, and optional lazy enrollment beneath a safe projects directory. See Connect an agent for the repository-isolation and consent model.

mcp

hsum mcp
hsum mcp --binding <UUID>

The no-argument form resolves the exact repository from the server process's working directory for managed Codex tasks. --binding pins a manual client to one trusted project. --project <NAME> selects a project only inside an already trusted direct-CLI context.

help, completions, man

hsum help error <SUBCODE>
hsum completions <SHELL>
hsum man

help error works offline and is version-pinned to the binary.