Hypha

The reference CMN client CLI — release spores, query synapses, resolve bonds, and manage your local mycelium.

Hypha is the local site manager for the Code Mycelial Network. It handles identity (Ed25519 keypairs), spore creation, signing, and spore consumption (taste, spawn, grow, absorb).

Full Reference: See docs/cli.md for the generated CLI reference.

Install

brew install cmnspore/tap/hypha   # macOS/Linux
scoop bucket add cmnspore https://github.com/cmnspore/scoop-bucket && scoop install hypha  # Windows
cargo install cmn-hypha           # any platform

Quick Start

Releasing Flow

# 1. Initialize a site (generates Ed25519 keypair)
hypha mycelium root cmn.dev

# 2. Deploy public/ directory so cmn.json is accessible over HTTPS
# No DNS TXT records required — public key is in cmn.json

# 3. Create spore metadata in your project
cd /path/to/project
hypha hatch --name my-tool --synopsis "A useful tool" --intent "Initial release"

# 4. Release (archive is default)
hypha release --domain cmn.dev

# With external git reference (archive also generated)
hypha release --domain cmn.dev --dist-git https://github.com/user/my-tool --dist-ref $(git rev-parse HEAD)

# 5. Deploy static files
rsync -avz ~/.cmn/mycelium/cmn.dev/public/ user@server:/var/www/

Consuming Flow

# Discover a spore
hypha sense cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2

# Taste: fetch to cache and evaluate safety
hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2
# Agent reviews code at cache_path, then records verdict:
hypha taste cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 --verdict safe

# Spawn your own project (checks taste verdict first)
hypha spawn cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2
cd my-tool

# Make changes
vim src/main.rs
git add . && git commit -m "my changes"

# Grow: sync updates from upstream
hypha grow

# Grow + update bonds: also check dependencies for newer versions
hypha grow --bond --synapse https://synapse.cmn.dev

# Absorb changes from other forks (AI-assisted)
hypha absorb cmn://fork.dev/b3.8cQnH4xPmZ2vLkJdRt7wNbA9sF3eYgU1hK6pXq5
# Then: "Read .cmn/absorb/ABSORB.md and help me absorb these changes"

# Publish your version
hypha mycelium root mydomain.com
hypha hatch --domain mydomain.com --intent "My improvements"
hypha release --domain mydomain.com

Sharing Taste Reports (via Hub)

Visitors without their own domain or server can share taste reports through a hosted hub, which auto-assigns a subdomain:

# One-time setup — generates key, computes subdomain, configures auto-submit
hypha mycelium root --hub cmnhub.com

# Register with the hub
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

# From now on, taste reports are automatically signed and submitted:
hypha taste cmn://cmn.dev/b3.HASH --verdict safe
# → shared: true (auto-submits to cmnhub.com, no --domain or --synapse needed)

The --hub flag sets up [defaults.taste] in config so every subsequent hypha taste --verdict automatically signs with your hub domain and submits to the hub.

Discovery & Evolution Tracking

# Search for spores by keyword (semantic search)
hypha search "HTTP client library" --synapse https://synapse.cmn.dev
hypha search "database" --synapse https://synapse.cmn.dev --domain cmn.dev --limit 5
hypha search "crypto" --synapse https://synapse.cmn.dev --license MIT

# Query bond graph — descendants (default direction: in)
hypha lineage cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 --synapse https://synapse.example.com

# Trace ancestors (direction: out)
hypha lineage cmn://cmn.dev/b3.3yMR7vZQ9hL2xKJdFtN8wPcB6sY1mXgU4eH5pTa2 --direction out --synapse https://synapse.example.com

# Auto-discover and absorb from bonds
hypha absorb --discover --synapse https://synapse.example.com

Commands Overview

# Releasing: Site management
hypha mycelium root <DOMAIN>                # Initialize site with keypair
hypha mycelium status                  # Show site status
hypha mycelium pulse --synapse <URL> --file <FILE>  # Notify synapse indexer

# Releasing: Spore management
hypha hatch [OPTIONS]                  # Create/update spore.core.json
hypha hatch bond set/remove/clear      # Manage bonds in spore.core.json
hypha hatch tree set/show              # Manage tree configuration
hypha release --domain <DOMAIN> [DIST]       # Sign and release

# Consuming: Discover & taste
hypha sense <URI>                      # Resolve URI, show metadata
hypha taste <URI>                      # Fetch to cache, evaluate safety
hypha taste <URI> --verdict safe       # Record verdict (auto-submits if hub configured)

# Hub setup (for visitors without a domain)
hypha mycelium root --hub cmnhub.com   # Generate key + configure auto-submit

# Consuming: Development
hypha spawn <URI>                      # Derive project with ownership
hypha grow                             # Sync from spawn source
hypha grow --bond --synapse <SYNAPSE>  # Also update + fetch bonds via lineage
hypha absorb <URI>... [--discover]     # Prepare for AI merge

# Consuming: Discovery
hypha search <QUERY> --synapse <SYNAPSE>      # Semantic search for spores
hypha lineage <URI> --synapse <SYNAPSE>         # Trace lineage (--direction in|out)

# Cache management
hypha cache list                       # List cached spores
hypha cache clean [--all]              # Remove cached items
hypha cache path <URI>                 # Show cache path

Output Format

Default is JSON (for AI agents). Hypha writes a stdout JSONL event stream (startup/progress/final result). Use --output plain or --output yaml for human-readable output. Formatting is handled by agent-first-data (output_json / output_plain / output_yaml).

# JSON (default)
hypha mycelium status cmn.dev
# {"kind":"result","result":{...},"trace":{...}}

# Plain (same data, rendered as logfmt key-value pairs)
hypha -o plain mycelium status cmn.dev
# kind=result result.domain=cmn.dev result.public_key=ed25519.5XmkQ9vZP8nL3xJdFtR7wNcA6sY2bKgU1eH9pXb4 result.site_path=/home/user/.cmn/mycelium/cmn.dev result.spore_count=5

Development

# Build
cargo build

# Test
cargo test

# Manual testing
export CMN_HOME=/tmp/cmn-test
hypha mycelium root test.local
hypha -o plain mycelium status

# Cleanup
rm -rf /tmp/cmn-test && unset CMN_HOME

Documentation

Regenerate the CLI reference with the project entrypoint (it prepends the docs/cli.md header, then appends hypha --help --recursive --output markdown):

scripts/projects.sh docs cmn-hypha
scripts/projects.sh docs cmn-hypha --dry-run

Running the bare hypha --help --recursive --output markdown only prints the body — use the project entrypoint so the header stays in sync.