Hypha CLI

Hypha CLI (tools/hypha-cli)

hypha is the command-line tool that fetches upstream OMG sources and generates the knowledge base. It is what the version-management skill drives conversationally on your behalf, and what the SessionStart hook calls to check for updates – but it is a normal standalone CLI you can also run yourself.

Installation

• Dotnet tool (needs the .NET 10 SDK):

  dotnet tool install --global Hypha.Tools
  

• Self-contained archive: download the per-platform build (~80 MB, bundles the runtime) from the Releases page for win-x64, linux-x64, osx-x64 or osx-arm64.

• In a source checkout, without installing anything:

  dotnet run --project tools/hypha-cli/Hypha.Tools -- <verb>
  

Verbs

All verbs accept --repository-root, --token, --log-level and --no-logo.

Verb	Does
hypha discover	Lists the releases both upstream repositories offer (--limit 0 for the full list)
hypha fetch --tag <tag> [--no-default] [--no-specs]	Downloads XMI, textual sources and (by default) spec PDFs into sources/<tag>/, records the install in knowledge/versions.json, and switches the default unless --no-default is given
hypha generate [artifact] [--tag <tag>] [--output <dir>]	Generates the knowledge base; with nothing narrowed, generates every artifact for every installed release
hypha list	Lists installed releases and the current default
hypha use --tag <release>	Switches the default among already-installed releases
hypha remove --tag <release> [--force]	Deletes one release's sources/ and knowledge/ files; refuses on the current default or the last remaining release unless --force is given
hypha check [--json]	Read-only comparison of what is installed against what upstream offers; the one verb the SessionStart hook drives – it never fetches, generates or deletes
hypha move-window --tag <release> [--keep N]	Maintainer-only. Fetch → regenerate → re-extract spec text → re-bless the Hypha.MetamodelGen.Tests Expected/ fixtures → a final self-consistency check → prune whichever locally-installed releases fall outside --keep (default 2). Needs a full source checkout and a provisioned tools/spec-extract virtualenv, since it shells out to dotnet test/pytest as subordinate steps

Generated artifacts, in the order they run (see Generation Pipelines#order): metamodel, grammar-references, textual-notation, model-library, spec, cross-references, discovered from the registered IKnowledgeGenerator implementations, never hardcoded, so adding a generator adds its verb rather than requiring a CLI change. spec is unlike the rest: it needs the OMG PDFs (hypha fetch gets them by default) and, the first time, fetches and caches its own copy of uv to run tools/spec-extract through – see Generation Pipelines#tools-spec-extract.

Examples

hypha discover
hypha fetch --tag 2026-05
hypha generate
hypha generate metamodel --tag 2026-05
hypha generate --output /tmp/knowledge
hypha check --json

Exit codes

Code	Meaning
0	Success
1	Nothing to do, or a generator refused
2	Usage error
130	Cancelled

Rate limits

The anonymous GitHub API allows 60 requests/hour. Set --token, GITHUB_TOKEN or GH_TOKEN to raise that ceiling for discover/fetch/check.

Building and testing

dotnet build mycelium-hypha.sln
dotnet test tools/hypha-cli/Hypha.Tools.Tests/Hypha.Tools.Tests.csproj

KnowledgeRegenerationTests (in Hypha.Tools.Tests) regenerates into a scratch folder – via HyphaKnowledgeOptions.OutputRoot – and byte-compares two independent runs against each other, proving the generators are deterministic without touching any tracked file. See Developers Experience for the wider "the CLI generates, the tests verify" convention this follows.

Publishing a self-contained build:

dotnet publish tools/hypha-cli/Hypha.Tools -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish/win-x64

Hypha.Tools.Hook

A separate, small project from the main CLI: the SessionStart hook binary. It is NativeAOT-published rather than self-contained, so it stays single-digit MB with no runtime behind it – deliberately kept free of dependencies (like Handlebars.Net or uml4net) that would block ahead-of-time compilation elsewhere in the solution:

dotnet publish tools/hypha-cli/Hypha.Tools.Hook -c Release -r win-x64 -p:PublishAot=true -o publish/hook/win-x64

AOT publishing needs a platform linker ("Desktop development with C++" on Windows, clang on Linux/macOS). See Skills and Agents#the-sessionstart-hook for what it does at session start, and Build and Release for how the committed hooks/native/<rid>/ binaries are built and shipped.