The reference CMN client CLI — release spores, query synapses, resolve bonds, and manage your local mycelium.
hypha 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 | hypha only | Name, version, and build identity as one protocol result. |
--docs | hypha only | This document, rendered from the registry. |
--output <FORMAT> | per output contract | Render as json, yaml, plain (default json). |
--output-to <DESTINATION> | per output contract | Route results and diagnostics to split, stdout, stderr (default split). |
--stdout-file <PATH>, --stderr-file <PATH> | per output contract | Append that stream to a file instead. |
Success output is protocol events, on those terms, unless a command’s own Output line says otherwise.
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
hypha absorb— Prepare spores for AI-assisted mergehypha bond— Fetch bonds from spore.core.jsonhypha cache clean— Remove old or all cached itemshypha cache list— List cached sporeshypha cache path— Show a cached spore’s filesystem pathhypha config list— Show merged Hypha configurationhypha config set— Set one dotted configuration keyhypha grow— Update a spawned working copy through Synapse lineagehypha hatch— Create or update spore.core.jsonhypha hatch bond clear— Remove every bondhypha hatch bond remove— Remove bonds matching a URI, relation, or bothhypha hatch bond set— Add or update one bond by URIhypha hatch bond sync— Reconcile one relation to a declarative JSON spechypha hatch tree set— Set tree hashing configurationhypha hatch tree show— Show tree hashing configurationhypha lineage— Trace descendants or ancestors of a sporehypha mycelium nutrient add— Add or update one nutrient methodhypha mycelium nutrient clear— Remove every nutrient methodhypha mycelium nutrient remove— Remove one nutrient methodhypha mycelium pulse— Send a signed mycelium to a Synapsehypha mycelium root— Establish or update a domain sitehypha mycelium serve— Serve a local mycelium site over HTTPhypha mycelium spore unyank— Restore a delisted spore from its retained manifesthypha mycelium spore yank— Delist a spore while retaining published byteshypha mycelium status— Show local site statushypha release— Sign and publish a sporehypha replicate— Copy spores to another domain without changing hasheshypha search— Search spores through a Synapsehypha sense— Resolve a CMN URI and show its metadatahypha skill install— Install or refresh the bundled skillhypha skill status— Inspect whether the bundled skill is currenthypha skill uninstall— Remove the bundled skillhypha spawn— Create a working copy of a sporehypha synapse add— Add a Synapse nodehypha synapse config— Configure credentials for one Synapsehypha synapse discover— Discover Synapse instanceshypha synapse health— Check one Synapse instancehypha synapse list— List configured Synapse nodeshypha synapse remove— Remove a Synapse nodehypha synapse use— Select the default Synapse nodehypha taste— Download a spore for review or record a verdict
hypha absorb
Prepare spores for AI-assisted merge
absorb_explicit — Absorb the listed URIs
hypha absorb [--log <CATEGORY>...] <CMN_URL>... [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--max-depth <COUNT>]absorb_discover — Discover descendants and absorb them
hypha absorb [--log <CATEGORY>...] --discover [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--max-depth <COUNT>]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | One or more spore URIs |
--discover | Discover descendants through Synapse |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
--max-depth | Maximum lineage depth |
hypha bond
Fetch bonds from spore.core.json
hypha bond [--log <CATEGORY>...] [--clean] [--status]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--clean | Remove cached bonds no longer declared |
--status | Show status without fetching |
hypha cache clean
Remove old or all cached items
hypha cache clean [--log <CATEGORY>...] [--all]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--all | Remove every cached item |
hypha cache list
List cached spores
hypha cache list [--log <CATEGORY>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
hypha cache path
Show a cached spore’s filesystem path
hypha cache path [--log <CATEGORY>...] <CMN_URL>| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | Spore URI |
hypha config list
Show merged Hypha configuration
hypha config list [--log <CATEGORY>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
hypha config set
Set one dotted configuration key
hypha config set [--log <CATEGORY>...] <KEY> <VALUE>| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
KEY | Dotted configuration path |
VALUE | Value to store |
hypha grow
Update a spawned working copy through Synapse lineage
hypha grow [--log <CATEGORY>...] [--dist <archive|git>] [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--bond]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--dist | Override the distribution source |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
--bond | Update and fetch bonds too |
hypha hatch
Create or update spore.core.json
hypha hatch [--log <CATEGORY>...] [--id <ID>] [--version <VERSION>] [--name <NAME>] [--domain <DOMAIN>] [--synopsis <TEXT>] [--intent <TEXT>...] [--mutations <TEXT>...] [--license <SPDX>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--id | Opaque spore identifier |
--version | Spore version |
--name | Display name |
--domain | Publisher domain |
--synopsis | Short description |
--intent | Permanent intent; repeat for more entries |
--mutations | Changes from the parent; repeat for more entries |
--license | SPDX license identifier |
hypha hatch bond clear
Remove every bond
hypha hatch bond clear [--log <CATEGORY>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
hypha hatch bond remove
Remove bonds matching a URI, relation, or both
hatch_bond_remove_uri — Match by URI, optionally narrowed by relation
hypha hatch bond remove [--log <CATEGORY>...] --uri <CMN_URL> [--relation <RELATION>]hatch_bond_remove_relation — Match every bond with one relation
hypha hatch bond remove [--log <CATEGORY>...] --relation <RELATION>
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--uri | URI to match |
--relation | Relation to match |
hypha hatch bond set
Add or update one bond by URI
hypha hatch bond set [--log <CATEGORY>...] --uri <CMN_URL> [--relation <RELATION>] [--id <ID>] [--reason <TEXT>] [--with <KEY=VALUE>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--uri | Bond URI and match key |
--relation | Bond relation |
--id | Bond id |
--reason | Why this bond exists |
--with | Bond parameter with a JSON value |
hypha hatch bond sync
Reconcile one relation to a declarative JSON spec
hypha hatch bond sync [--log <CATEGORY>...] --relation <RELATION> --spec <PATH_OR_JSON> [--domain <DOMAIN>] [--site-path <PATH>] [--check]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--relation | Relation to reconcile |
--spec | JSON spec file, inline JSON, or stdin |
--domain | Domain used to resolve omitted URIs |
--site-path | Custom mycelium site directory |
--check | Report drift without writing |
hypha hatch tree set
Set tree hashing configuration
hypha hatch tree set [--log <CATEGORY>...] [--algorithm <ALGORITHM>] [--exclude-names <NAME>...] [--follow-rules <FILE>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--algorithm | Tree hash algorithm |
--exclude-names | File or directory name to exclude |
--follow-rules | Ignore-rule file to follow |
hypha hatch tree show
Show tree hashing configuration
hypha hatch tree show [--log <CATEGORY>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
hypha lineage
Trace descendants or ancestors of a spore
hypha lineage [--log <CATEGORY>...] <CMN_URL> [--direction <in|out>] [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--max-depth <COUNT>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | Spore URI |
--direction | in for descendants, out for ancestors |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
--max-depth | Maximum traversal depth |
hypha mycelium nutrient add
Add or update one nutrient method
hypha mycelium nutrient add [--log <CATEGORY>...] <DOMAIN> --type <TYPE> [--with <KEY=VALUE>...] [--site-path <PATH>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--type | Nutrient method type |
--with | Nutrient parameter with a JSON value |
--site-path | Custom mycelium site directory |
hypha mycelium nutrient clear
Remove every nutrient method
hypha mycelium nutrient clear [--log <CATEGORY>...] <DOMAIN> [--site-path <PATH>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--site-path | Custom mycelium site directory |
hypha mycelium nutrient remove
Remove one nutrient method
hypha mycelium nutrient remove [--log <CATEGORY>...] <DOMAIN> --type <TYPE> [--site-path <PATH>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--type | Nutrient method type |
--site-path | Custom mycelium site directory |
hypha mycelium pulse
Send a signed mycelium to a Synapse
hypha mycelium pulse [--log <CATEGORY>...] --file <PATH> [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--file | Signed mycelium JSON file |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
hypha mycelium root
Establish or update a domain site
mycelium_root_domain — Create or update an explicitly named domain
hypha mycelium root [--log <CATEGORY>...] <DOMAIN> [--site-path <PATH>] [--name <NAME>] [--synopsis <TEXT>] [--bio <MARKDOWN>] [--endpoints-base <URL>]mycelium_root_hub — Create a taste-only identity under a hosted hub
hypha mycelium root [--log <CATEGORY>...] --hub <DOMAIN> [--site-path <PATH>] [--name <NAME>] [--synopsis <TEXT>] [--bio <MARKDOWN>]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--hub | Hosted taste hub |
--site-path | Custom mycelium site directory |
--name | Site or author name |
--synopsis | Brief site description |
--bio | Site or author bio |
--endpoints-base | Base URL for endpoints |
hypha mycelium serve
Serve a local mycelium site over HTTP
hypha mycelium serve [--log <CATEGORY>...] [<DOMAIN>] [--site-path <PATH>] [--port <PORT>]
Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--site-path | Custom mycelium site directory |
--port | TCP port |
hypha mycelium spore unyank
Restore a delisted spore from its retained manifest
hypha mycelium spore unyank [--log <CATEGORY>...] --id <SPORE_ID> [--domain <DOMAIN>] [--site-path <PATH>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--id | Spore id to restore |
--domain | Domain used to locate the site |
--site-path | Custom mycelium site directory |
hypha mycelium spore yank
Delist a spore while retaining published bytes
hypha mycelium spore yank [--log <CATEGORY>...] --id <SPORE_ID> [--domain <DOMAIN>] [--site-path <PATH>] [--purge]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--id | Spore id to delist |
--domain | Domain used to locate the site |
--site-path | Custom mycelium site directory |
--purge | Delete the published manifest and archive too |
hypha mycelium status
Show local site status
mycelium_status_domain — List sites or show one domain
hypha mycelium status [--log <CATEGORY>...] [<DOMAIN>] [--site-path <PATH>]mycelium_status_spore — Resolve one spore id from one domain
hypha mycelium status [--log <CATEGORY>...] <DOMAIN> [--site-path <PATH>] --id <SPORE_ID>
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Domain name |
--site-path | Custom mycelium site directory |
--id | Resolve a spore from the inventory |
hypha release
Sign and publish a spore
release_archive — Release from local source and archive
hypha release [--log <CATEGORY>...] --domain <DOMAIN> [--source <PATH>] [--site-path <PATH>] [--archive <zstd>] [--dry-run]release_git — Release with an external git distribution
hypha release [--log <CATEGORY>...] --domain <DOMAIN> [--source <PATH>] [--site-path <PATH>] --dist-git <URL> --dist-ref <REF> [--archive <zstd>] [--dry-run]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--domain | Target publisher domain |
--source | Spore source directory |
--site-path | Custom mycelium site directory |
--dist-git | External git repository |
--dist-ref | Tag, branch, or commit |
--archive | Generated archive format |
--dry-run | Compute the URI without writing |
hypha replicate
Copy spores to another domain without changing hashes
replicate_explicit — Replicate the listed URIs
hypha replicate [--log <CATEGORY>...] <CMN_URL>... --domain <DOMAIN> [--site-path <PATH>]replicate_refs — Replicate every declared non-self bond
hypha replicate [--log <CATEGORY>...] --refs --domain <DOMAIN> [--site-path <PATH>]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | One or more spore URIs |
--refs | Replicate every non-self bond |
--domain | Target publisher domain |
--site-path | Custom mycelium site directory |
hypha search
Search spores through a Synapse
hypha search [--log <CATEGORY>...] <QUERY> [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--domain <DOMAIN>] [--license <SPDX>] [--bonds <RELATION:URI>] [--limit <COUNT>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
QUERY | Search text |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
--domain | Filter by publisher domain |
--license | Filter by license |
--bonds | Comma-separated bond filters |
--limit | Maximum number of results |
hypha sense
Resolve a CMN URI and show its metadata
hypha sense [--log <CATEGORY>...] <CMN_URL> [--id <SPORE_ID>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | CMN URI to resolve |
--id | Resolve the latest spore with this id |
hypha skill install
Install or refresh the bundled skill
skill_install_standard — Use the selected agent’s standard skills directory
hypha skill install [--log <CATEGORY>...] [--agent <all|codex|claude-code|opencode>] [--scope <personal|project>] [--force]skill_install_explicit_directory — Use an explicit directory for one concrete agent
hypha skill install [--log <CATEGORY>...] --agent <codex|claude-code|opencode> [--scope <personal|project>] --skills-dir <PATH> [--force]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--agent | Agent target |
--scope | Install scope |
--skills-dir | Explicit skills directory |
--force | Replace an unmanaged target |
hypha skill status
Inspect whether the bundled skill is current
skill_status_standard — Use the selected agent’s standard skills directory
hypha skill status [--log <CATEGORY>...] [--agent <all|codex|claude-code|opencode>] [--scope <personal|project>] [--force]skill_status_explicit_directory — Use an explicit directory for one concrete agent
hypha skill status [--log <CATEGORY>...] --agent <codex|claude-code|opencode> [--scope <personal|project>] --skills-dir <PATH> [--force]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--agent | Agent target |
--scope | Install scope |
--skills-dir | Explicit skills directory |
--force | Replace an unmanaged target |
hypha skill uninstall
Remove the bundled skill
skill_uninstall_standard — Use the selected agent’s standard skills directory
hypha skill uninstall [--log <CATEGORY>...] [--agent <all|codex|claude-code|opencode>] [--scope <personal|project>] [--force]skill_uninstall_explicit_directory — Use an explicit directory for one concrete agent
hypha skill uninstall [--log <CATEGORY>...] --agent <codex|claude-code|opencode> [--scope <personal|project>] --skills-dir <PATH> [--force]
Arguments across every shape above:
| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--agent | Agent target |
--scope | Install scope |
--skills-dir | Explicit skills directory |
--force | Replace an unmanaged target |
hypha spawn
Create a working copy of a spore
hypha spawn [--log <CATEGORY>...] <CMN_URL> [<DIRECTORY>] [--vcs <git|none>] [--dist <archive|git>] [--bond]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | Spore URI to copy |
DIRECTORY | Target directory |
--vcs | Version-control initialization |
--dist | Preferred distribution source |
--bond | Fetch the spore’s bonds after spawning |
hypha synapse add
Add a Synapse node
hypha synapse add [--log <CATEGORY>...] <URL>| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
URL | Synapse URL |
hypha synapse config
Configure credentials for one Synapse
hypha synapse config [--log <CATEGORY>...] <DOMAIN> [--token-secret <TOKEN>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Synapse domain |
--token-secret | Token, or an empty string to clear |
hypha synapse discover
Discover Synapse instances
hypha synapse discover [--log <CATEGORY>...] [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
hypha synapse health
Check one Synapse instance
hypha synapse health [--log <CATEGORY>...] [<DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN_OR_URL | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
hypha synapse list
List configured Synapse nodes
hypha synapse list [--log <CATEGORY>...]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
hypha synapse remove
Remove a Synapse node
hypha synapse remove [--log <CATEGORY>...] <DOMAIN>| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Synapse domain |
hypha synapse use
Select the default Synapse node
hypha synapse use [--log <CATEGORY>...] <DOMAIN>| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
DOMAIN | Synapse domain |
hypha taste
Download a spore for review or record a verdict
hypha taste [--log <CATEGORY>...] <CMN_URL> [--verdict <sweet|fresh|safe|rotten|toxic>] [--notes <TEXT>] [--synapse <DOMAIN_OR_URL>] [--synapse-token-secret <TOKEN>] [--domain <DOMAIN>]| Argument | Meaning |
|---|---|
--log | Diagnostic category to emit; repeat or use comma-separated values |
CMN_URL | CMN URI to evaluate |
--verdict | Verdict to record |
--notes | Notes accompanying the verdict |
--synapse | Synapse domain or URL |
--synapse-token-secret | Authentication token overriding the configured Synapse token |
--domain | Domain used to sign a taste report |
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.