CLI reference
gnarl <command> [subcommand] [flags]
Global flags apply to every command.
| Flag | Default | Description |
|---|---|---|
--config <path> | ./gnarl.yaml | Config file to load |
--home <path> | ~/.gnarl | Identity, peer table, and local state |
--output <fmt> | text | text, json, or ndjson |
--log-level <lvl> | info | error, warn, info, debug, trace |
--no-color | off | Disable ANSI color |
node
gnarl node up [--data <path>] [--listen <addr>] [--entry-only] [--relay]
gnarl node status [--watch]
gnarl node drain [--timeout 60s]
gnarl node down
up starts the process, builds or opens the local index, and begins serving. It
does not announce to any network — that is join.
| Flag | Description |
|---|---|
--data <path> | Corpus to index. Repeatable. Opened read-only. |
--listen <addr> | Bind address. Default 0.0.0.0:7420. |
--entry-only | Coordinate queries, hold no index. |
--relay | Forward manifests and queries across a boundary. |
--watch | (status) Refresh in place until interrupted. |
join / leave
gnarl join --network <name> [--bootstrap <addrs>] [--psk-file <path>]
gnarl leave [--network <name>]
| Flag | Description |
|---|---|
--network <name> | Network to announce into. public for the open network. |
--bootstrap <addrs> | Comma-separated host:port peers to contact first. |
--psk-file <path> | Pre-shared key for a private network. |
index
gnarl index build <name>
gnarl index publish <name>
gnarl index unpublish <name>
gnarl index refresh <name>
gnarl index watch <name>
gnarl index list
gnarl index drop <name> [--force]
build creates the index locally. publish announces its manifest. The split is
deliberate: you always get to look at a manifest before the network sees it.
manifest
gnarl manifest show <index> [--output json]
gnarl manifest verify <file>
gnarl manifest list [--peer <node-id>]
search
gnarl search <query> [flags]
| Flag | Default | Description |
|---|---|---|
--local | off | Query only this node |
--limit <n> | 10 | Hits to return |
--index <name> | all | Restrict to one index. Repeatable. |
--max-nodes <n> | 64 | Fan-out ceiling |
--deadline <dur> | 750ms | Give up on stragglers after this |
--trust <mode> | verified | verified, pinned-only, or any |
--explain | off | Print the plan, the roster, and the timings |
gnarl search "glacier retreat" --index imagery --limit 25 --explain
peer
gnarl peer list [--healthy]
gnarl peer show <node-id>
gnarl peer trust <node-id> [--label <name>]
gnarl peer untrust <node-id>
gnarl peer block <node-id>
identity
gnarl identity create [--label <name>]
gnarl identity show
gnarl identity rotate [--keep-old <dur>]
gnarl identity export --out <path>
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic failure |
2 | Bad usage or config |
3 | Query returned incomplete coverage and --require-complete was set |
4 | Signature verification failed |
5 | Refused by policy |