Hypha CLI Reference

Regenerate with hypha --help-markdown.

Command-Line Help for hypha

This document contains the help content for the hypha command-line program.

Command Overview:

hypha

CMN Client - A bio-digital extension for Visitors to release and absorb Spores

Usage: hypha [OPTIONS] <COMMAND>

All output follows Agent-First Data format: {“code”: “ok”, “result”: {…}, “trace”: {…}}

Quick start (try with cmn.dev): hypha sense cmn://cmn.dev hypha sense cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha cache list

Subcommands:
Options:

hypha sense

Resolve a CMN URI and show metadata without downloading

Usage: hypha sense <URI>

URI types: cmn://DOMAIN List all spores on a site cmn://DOMAIN/HASH View a specific spore

Examples: hypha sense cmn://cmn.dev hypha sense cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha sense cmn://cmn.dev -o yaml

Arguments:

hypha taste

Evaluate spore: download for review, or record a verdict

Usage: hypha taste [OPTIONS] <URI>

Without –verdict: downloads the spore for local review. With –verdict: records a verdict (sweet, fresh, safe, rotten, toxic).

Examples: hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –verdict safe –notes “Reviewed: clean code” hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –verdict safe –domain cmn.dev –synapse https://synapse.cmn.dev

Arguments:
Options:

hypha spawn

Create a working copy of a spore (auto-detects best distribution format)

Usage: hypha spawn [OPTIONS] <URI> [DIRECTORY]

Distribution sources (auto-detected): archive Download .tar.zst archive (default, fastest) git Clone from dist.git URL if available

Examples: hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 my-project –vcs git hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –dist git

Arguments:
Options:

hypha grow

Pull latest changes from spawn source via Synapse lineage

Usage: hypha grow [OPTIONS]

Run inside a previously spawned directory to update it. Uses Synapse lineage to discover newer versions from the same publisher.

If local files have been modified (git dirty or tree hash mismatch), grow refuses to overwrite them and shows the cache path for manual merge.

Examples: hypha grow hypha grow –synapse synapse.cmn.dev hypha grow –dist git hypha grow –dist archive hypha grow –bond –synapse synapse.cmn.dev

Options:

hypha absorb

Prepare spores for AI-assisted merge

Usage: hypha absorb [OPTIONS] [URIS]...

Absorb downloads spores into .cmn/absorb/ for AI-assisted merge. Use –discover to auto-discover descendants via Synapse.

Examples: hypha absorb cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 hypha absorb –discover –synapse https://synapse.cmn.dev hypha absorb –discover –synapse https://synapse.cmn.dev –max-depth 5

Arguments:
Options:

hypha bond

Fetch all bonds from spore.core.json to .cmn/bonds/

Usage: hypha bond [OPTIONS]

Examples: hypha bond hypha bond –status hypha bond –clean

Options:

hypha replicate

Copy a spore to your domain (same hash, re-signed capsule)

Usage: hypha replicate [OPTIONS] --domain <DOMAIN> [URIS]...

Replicates spores from another domain to yours. The hash stays the same because core + core_signature are preserved. Only capsule_signature changes.

Examples: hypha replicate cmn://other.dev/HASH –domain my.dev hypha replicate –refs –domain my.dev

Arguments:
Options:

hypha hatch

Create or update spore.core.json in working directory

Usage: hypha hatch [OPTIONS] hatch <COMMAND>

Examples: hypha hatch –id my-tool –name “My Tool” –synopsis “A useful tool” hypha hatch –intent “Provide a reusable HTTP client for CMN agents” –mutations “Initial release” hypha hatch –license MIT –domain cmn.dev

Subcommands: hypha hatch bond set/remove/clear Manage bonds in spore.core.json hypha hatch tree set/show Manage tree configuration

Subcommands:
Options:

hypha hatch bond

Manage bonds in spore.core.json

Usage: hypha hatch bond <COMMAND>

Examples: hypha hatch bond set –uri cmn://cmn.dev/b3.abc –relation follows –id my-lib –reason “Core library” hypha hatch bond set –uri cmn://cmn.dev/b3.abc –with ‘mints=[“https://mint.example.com”]’ hypha hatch bond remove –relation follows hypha hatch bond clear

Subcommands:

hypha hatch bond set

Add or update a bond (upsert by URI)

Usage: hypha hatch bond set [OPTIONS] --uri <URI>

Options:

hypha hatch bond remove

Remove bonds by URI and/or relation

Usage: hypha hatch bond remove [OPTIONS]

Options:

hypha hatch bond clear

Remove all bonds

Usage: hypha hatch bond clear

hypha hatch tree

Manage tree configuration in spore.core.json

Usage: hypha hatch tree <COMMAND>

Subcommands:

hypha hatch tree set

Set tree configuration fields

Usage: hypha hatch tree set [OPTIONS]

Options:

hypha hatch tree show

Show current tree configuration

Usage: hypha hatch tree show

hypha release

Sign and publish spore to mycelium site

Usage: hypha release [OPTIONS] --domain <DOMAIN>

Requires hypha mycelium root first to set up the site.

Examples: hypha release –domain cmn.dev hypha release –domain cmn.dev –source ./my-spore hypha release –domain cmn.dev –dry-run # pre-compute URI without releasing hypha release –domain cmn.dev –archive zstd hypha release –domain cmn.dev –dist-git https://github.com/user/repo –dist-ref v1.0

Options:

hypha lineage

Trace spore lineage: descendants (in, default) or ancestors (out)

Usage: hypha lineage [OPTIONS] <URI>

Direction: –direction in Find descendants / forks (default) –direction out Trace ancestors / spawn chain

Examples: hypha lineage cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –synapse https://synapse.cmn.dev hypha lineage cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –direction out –synapse https://synapse.cmn.dev hypha lineage cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 –synapse https://synapse.cmn.dev –max-depth 5

Arguments:
Options:

Search for spores by keyword (semantic search via Synapse)

Usage: hypha search [OPTIONS] <QUERY>

Examples: hypha search “protocol spec” –synapse https://synapse.cmn.dev hypha search “data format” –synapse https://synapse.cmn.dev –domain cmn.dev hypha search “agent tools” –synapse https://synapse.cmn.dev –license MIT –limit 5 hypha search “http client” –bonds spawned_from:cmn://cmn.dev/b3.abc123

Arguments:
Options:

hypha mycelium

Manage local mycelium site

Usage: hypha mycelium <COMMAND>

Subcommands:

hypha mycelium root

Establish a new site for a domain (or update existing)

Usage: hypha mycelium root [OPTIONS] [DOMAIN]

Creates ~/.cmn/mycelium// with key pair and site structure. Run this once before hypha release.

With –hub, creates a taste-only account on a hosted hub (e.g. cmnhub.com):

  1. Generates ed25519 key pair
  2. Computes subdomain from pubkey (ed-.hub)
  3. Creates taste-only cmn.json with taste endpoint
  4. Registers hub as a synapse node
  5. Sets [defaults.taste] so hypha taste auto-submits

After –hub, register with the hub then taste without extra flags: curl -X POST https://cmnhub.com/synapse/pulse -H ‘Content-Type: application/json’
-d @~/.cmn/mycelium/ed-xxx.cmnhub.com/public/.well-known/cmn.json hypha taste cmn://example.com/b3.HASH –verdict safe

Examples: hypha mycelium root cmn.dev –name “CMN” –synopsis “Code Mycelial Network” hypha mycelium root cmn.dev –endpoints-base https://cmn.dev hypha mycelium root example.com –site-path /custom/path hypha mycelium root –hub cmnhub.com

Arguments:
Options:

hypha mycelium status

Show site status

Usage: hypha mycelium status [OPTIONS] [DOMAIN]

Examples: hypha mycelium status hypha mycelium status cmn.dev

Arguments:
Options:

hypha mycelium serve

Start a local HTTP server to serve the site (for debugging)

Usage: hypha mycelium serve [OPTIONS] [DOMAIN]

Examples: hypha mycelium serve hypha mycelium serve cmn.dev –port 3000

Arguments:
Options:

hypha mycelium nutrient

Manage nutrient methods (add/remove/clear)

Usage: hypha mycelium nutrient <COMMAND>

Examples: hypha mycelium nutrient add cmn.dev –type lightning_address –with address=user@example.com hypha mycelium nutrient add cmn.dev –type url –with url=https://example.com –with label=Donate hypha mycelium nutrient remove cmn.dev –type url hypha mycelium nutrient clear cmn.dev

Subcommands:

hypha mycelium nutrient add

Add or update a nutrient method (upsert by type)

Usage: hypha mycelium nutrient add [OPTIONS] --type <TYPE> <DOMAIN>

Arguments:
Options:

hypha mycelium nutrient remove

Remove a nutrient method by type

Usage: hypha mycelium nutrient remove [OPTIONS] --type <TYPE> <DOMAIN>

Arguments:
Options:

hypha mycelium nutrient clear

Remove all nutrient methods

Usage: hypha mycelium nutrient clear [OPTIONS] <DOMAIN>

Arguments:
Options:

hypha mycelium pulse

Send a pulse to a synapse indexer

Usage: hypha mycelium pulse [OPTIONS] --file <FILE>

Examples: hypha mycelium pulse –synapse synapse.cmn.dev –file ~/.cmn/mycelium/cmn.dev/public/cmn/mycelium/.json hypha mycelium pulse –synapse https://synapse.cmn.dev –file ~/.cmn/mycelium/cmn.dev/public/cmn/mycelium/.json

Options:

hypha synapse

Manage Synapse node connections

Usage: hypha synapse <COMMAND>

Subcommands:

hypha synapse discover

Discover Synapse instances via the network

Usage: hypha synapse discover [OPTIONS]

Examples: hypha synapse discover hypha synapse discover –synapse https://synapse.cmn.dev

Options:

hypha synapse list

List configured Synapse nodes

Usage: hypha synapse list

Examples: hypha synapse list

hypha synapse health

Check health of a Synapse instance

Usage: hypha synapse health [OPTIONS] [SYNAPSE]

Examples: hypha synapse health hypha synapse health synapse.cmn.dev hypha synapse health https://synapse.cmn.dev

Arguments:
Options:

hypha synapse add

Add a Synapse node

Usage: hypha synapse add <URL>

Examples: hypha synapse add https://synapse.cmn.dev

Arguments:

hypha synapse remove

Remove a Synapse node

Usage: hypha synapse remove <DOMAIN>

Examples: hypha synapse remove synapse.cmn.dev

Arguments:

hypha synapse use

Set default Synapse node

Usage: hypha synapse use <DOMAIN>

Examples: hypha synapse use synapse.cmn.dev

Arguments:

hypha synapse config

Configure a Synapse node (token, etc.)

Usage: hypha synapse config [OPTIONS] <DOMAIN>

Examples: hypha synapse config synapse.cmn.dev –token-secret sk-abc123 hypha synapse config synapse.cmn.dev –token-secret “” # clear token

Arguments:
Options:

hypha cache

Manage local cache

Usage: hypha cache <COMMAND>

Subcommands:

hypha cache list

List all cached spores

Usage: hypha cache list

Examples: hypha cache list hypha cache list -o yaml

hypha cache clean

Remove old or all cached items

Usage: hypha cache clean [OPTIONS]

Examples: hypha cache clean –all

Options:

hypha cache path

Show local filesystem path for a cached spore

Usage: hypha cache path <URI>

Examples: hypha cache path cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

Arguments:

hypha config

View or modify hypha configuration

Usage: hypha config <COMMAND>

Subcommands:

hypha config list

Show current configuration (merged defaults + config.toml)

Usage: hypha config list

Examples: hypha config list hypha config list -o yaml

hypha config set

Set a configuration value

Usage: hypha config set <KEY> <VALUE>

Dotted keys map to TOML sections: cache.path Custom cache directory cache.cmn_ttl_s cmn.json cache TTL in seconds cache.key_trust_ttl_s Key trust cache TTL in seconds cache.key_trust_refresh_mode Key trust refresh mode: expired | always | offline cache.key_trust_synapse_witness_mode Key trust fallback when domain is offline: allow | require_domain cache.clock_skew_tolerance_s Clock skew tolerance in seconds for key trust TTL (default: 300) defaults.synapse Default synapse domain defaults.domain Default domain for publishing (release) defaults.taste.synapse Synapse to submit taste reports to (overrides defaults.synapse for taste) defaults.taste.domain Domain to sign taste reports with (overrides defaults.domain for taste)

Examples: hypha config set cache.cmn_ttl_s 600 hypha config set cache.key_trust_ttl_s 604800 hypha config set cache.key_trust_refresh_mode offline hypha config set cache.key_trust_synapse_witness_mode require_domain hypha config set cache.path /tmp/hypha-cache hypha config set defaults.synapse synapse.cmn.dev hypha config set defaults.taste.synapse cmnhub.com hypha config set defaults.taste.domain ed-xxx.cmnhub.com

Arguments: