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.

ArgumentWhereWhat it does
--helpevery commandEvery legal shape of that command, complete, plus its subcommands. JSON by default; --output plain for a terminal.
--versionhypha onlyName, version, and build identity as one protocol result.
--docshypha onlyThis document, rendered from the registry.
--output <FORMAT>per output contractRender as json, yaml, plain (default json).
--output-to <DESTINATION>per output contractRoute results and diagnostics to split, stdout, stderr (default split).
--stdout-file <PATH>, --stderr-file <PATH>per output contractAppend 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 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLOne or more spore URIs
--discoverDiscover descendants through Synapse
--synapseSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token
--max-depthMaximum lineage depth

hypha bond

Fetch bonds from spore.core.json

hypha bond [--log <CATEGORY>...] [--clean] [--status]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--cleanRemove cached bonds no longer declared
--statusShow status without fetching

hypha cache clean

Remove old or all cached items

hypha cache clean [--log <CATEGORY>...] [--all]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--allRemove every cached item

hypha cache list

List cached spores

hypha cache list [--log <CATEGORY>...]
ArgumentMeaning
--logDiagnostic 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>
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLSpore URI

hypha config list

Show merged Hypha configuration

hypha config list [--log <CATEGORY>...]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values

hypha config set

Set one dotted configuration key

hypha config set [--log <CATEGORY>...] <KEY> <VALUE>
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
KEYDotted configuration path
VALUEValue 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]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--distOverride the distribution source
--synapseSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token
--bondUpdate 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--idOpaque spore identifier
--versionSpore version
--nameDisplay name
--domainPublisher domain
--synopsisShort description
--intentPermanent intent; repeat for more entries
--mutationsChanges from the parent; repeat for more entries
--licenseSPDX license identifier

hypha hatch bond clear

Remove every bond

hypha hatch bond clear [--log <CATEGORY>...]
ArgumentMeaning
--logDiagnostic 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--uriURI to match
--relationRelation 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>...]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--uriBond URI and match key
--relationBond relation
--idBond id
--reasonWhy this bond exists
--withBond 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]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--relationRelation to reconcile
--specJSON spec file, inline JSON, or stdin
--domainDomain used to resolve omitted URIs
--site-pathCustom mycelium site directory
--checkReport 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>...]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--algorithmTree hash algorithm
--exclude-namesFile or directory name to exclude
--follow-rulesIgnore-rule file to follow

hypha hatch tree show

Show tree hashing configuration

hypha hatch tree show [--log <CATEGORY>...]
ArgumentMeaning
--logDiagnostic 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLSpore URI
--directionin for descendants, out for ancestors
--synapseSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token
--max-depthMaximum 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--typeNutrient method type
--withNutrient parameter with a JSON value
--site-pathCustom mycelium site directory

hypha mycelium nutrient clear

Remove every nutrient method

hypha mycelium nutrient clear [--log <CATEGORY>...] <DOMAIN> [--site-path <PATH>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--site-pathCustom mycelium site directory

hypha mycelium nutrient remove

Remove one nutrient method

hypha mycelium nutrient remove [--log <CATEGORY>...] <DOMAIN> --type <TYPE> [--site-path <PATH>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--typeNutrient method type
--site-pathCustom 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--fileSigned mycelium JSON file
--synapseSynapse domain or URL
--synapse-token-secretAuthentication 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--hubHosted taste hub
--site-pathCustom mycelium site directory
--nameSite or author name
--synopsisBrief site description
--bioSite or author bio
--endpoints-baseBase 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.

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--site-pathCustom mycelium site directory
--portTCP 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--idSpore id to restore
--domainDomain used to locate the site
--site-pathCustom 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]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--idSpore id to delist
--domainDomain used to locate the site
--site-pathCustom mycelium site directory
--purgeDelete 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINDomain name
--site-pathCustom mycelium site directory
--idResolve 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--domainTarget publisher domain
--sourceSpore source directory
--site-pathCustom mycelium site directory
--dist-gitExternal git repository
--dist-refTag, branch, or commit
--archiveGenerated archive format
--dry-runCompute 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLOne or more spore URIs
--refsReplicate every non-self bond
--domainTarget publisher domain
--site-pathCustom mycelium site directory

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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
QUERYSearch text
--synapseSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token
--domainFilter by publisher domain
--licenseFilter by license
--bondsComma-separated bond filters
--limitMaximum number of results

hypha sense

Resolve a CMN URI and show its metadata

hypha sense [--log <CATEGORY>...] <CMN_URL> [--id <SPORE_ID>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLCMN URI to resolve
--idResolve 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--agentAgent target
--scopeInstall scope
--skills-dirExplicit skills directory
--forceReplace 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--agentAgent target
--scopeInstall scope
--skills-dirExplicit skills directory
--forceReplace 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:

ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--agentAgent target
--scopeInstall scope
--skills-dirExplicit skills directory
--forceReplace 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]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLSpore URI to copy
DIRECTORYTarget directory
--vcsVersion-control initialization
--distPreferred distribution source
--bondFetch the spore’s bonds after spawning

hypha synapse add

Add a Synapse node

hypha synapse add [--log <CATEGORY>...] <URL>
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
URLSynapse URL

hypha synapse config

Configure credentials for one Synapse

hypha synapse config [--log <CATEGORY>...] <DOMAIN> [--token-secret <TOKEN>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINSynapse domain
--token-secretToken, 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
--synapseSynapse domain or URL
--synapse-token-secretAuthentication 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAIN_OR_URLSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token

hypha synapse list

List configured Synapse nodes

hypha synapse list [--log <CATEGORY>...]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values

hypha synapse remove

Remove a Synapse node

hypha synapse remove [--log <CATEGORY>...] <DOMAIN>
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINSynapse domain

hypha synapse use

Select the default Synapse node

hypha synapse use [--log <CATEGORY>...] <DOMAIN>
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
DOMAINSynapse 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>]
ArgumentMeaning
--logDiagnostic category to emit; repeat or use comma-separated values
CMN_URLCMN URI to evaluate
--verdictVerdict to record
--notesNotes accompanying the verdict
--synapseSynapse domain or URL
--synapse-token-secretAuthentication token overriding the configured Synapse token
--domainDomain used to sign a taste report

Exit codes

CodeMeaning
0The command ran and succeeded.
1The command ran and failed. The event carries a domain error.code.
2The 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.