Hypha

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.