The reference CMN indexer — ingests signed manifests, indexes spores and myceliums, serves discovery queries, and syncs across instances via Nostr.
synapse is compiled from a closed cli-spec-v1 registry: one source for argv parsing, typed invocation values, which parameter combinations are legal, output contracts, and help. An invocation runs only when it matches exactly one registered combination.
Global arguments
AFDATA registers these itself, so the syntax in Commands leaves them out.
| Argument | Where | What it does |
|---|---|---|
--help | every command | Every legal shape of that command, complete, plus its subcommands. JSON by default; --output plain for a terminal. |
--version | synapse only | Name, version, and build identity as one protocol result. |
--docs | synapse only | This document, rendered from the registry. |
--stdout-file <PATH>, --stderr-file <PATH> | per output contract | Append that stream to a file instead. |
A shape is one legal set of arguments that may appear together, under a stable id. Where a command has more than one, each id is a heading below. --help returns them all at once, so discovering a command costs one call; there is no recursive mode across commands, and this document is that view.
Commands
synapse— Run the indexer or rebuild its search vectors
synapse
Run the indexer or rebuild its search vectors
serve — Run the federated indexer services
synapse [--config <PATH>]rebuild-search — Re-embed every stored spore and exit
synapse [--config <PATH>] --rebuild-searchOutput: raw bytes on success; rejects --output and --output-to; redirect with --stdout-file or --stderr-file. Failures are still strict JSON on stderr.
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--config | Configuration file path |
--rebuild-search | Rebuild the search vector index from storage, then exit; requires the ruvector feature and a running embedding server |
Exit codes
| Code | Meaning |
|---|---|
| 0 | The command ran and succeeded. |
| 1 | The command ran and failed. The event carries a domain error.code. |
| 2 | The invocation was rejected before anything ran. error.code is one of the cli_* codes below. |
The split is the useful one for a caller: exit 2 means the call was never made, so retrying it unchanged cannot help, while exit 1 means it was.
CLI errors
Every structural failure emits one strict JSON kind:"error" event on stderr, leaves stdout empty, and exits 2. The code names the failure — cli_unknown_argument for an unknown spelling, cli_unregistered_combination for registered arguments in a mixture that is not, and one each for cli_unknown_command, cli_missing_argument_value, cli_invalid_argument_value, cli_duplicate_argument, cli_unexpected_positional, and cli_invalid_utf8. message identifies a safe argument spelling or the failure category and hint gives the command to run next; neither ever quotes a raw value, including secrets. These are decided before any config, secret source, filesystem, network, or domain I/O.
Two exit-1 codes describe the tool itself rather than the call: cli_invocation_invalid means the program misread its own resolved invocation — an unknown action id, or an argument id the selected combination cannot produce — and output_setup_failed means an output sink (--stdout-file, --stderr-file, stream redirection) could not be established. Both are defects to report, not inputs to correct; retrying the same command cannot help.
Domain failures (exit 1) carry their own stable error.code instead, drawn from whatever this tool defines rather than from the cli_* set. No error message quotes a raw value it was given — an error event is routinely logged, and the input may hold secrets.