CLI Reference¶

NON-NORMATIVE.

The morphism CLI (@morphism-systems/cli) provides governance tooling for any project following the Morphism categorical governance framework.

Install:

npm install -g @morphism-systems/cli
# or use via npx
npx morphism <command>

Global flags¶

Flag	Description
`--help`, `-h`	Show command help
`--version`, `-V`	Print CLI version

Commands¶

`morphism init`¶

Description: Initialize .morphism/ configuration in the current project. Creates .morphism/config.json with default governance settings. Skips silently if .morphism/ already exists.

Usage:

morphism init

Flags: None beyond global help flags.

Example:

morphism init

Expected output:

Initialized .morphism/ with default config

Creates .morphism/config.json with default kernel settings: governance.kernel, governance.invariants = 7, governance.tenets = 10, metrics.convergence_threshold = 1.0, metrics.drift_threshold = 15.

`morphism doctor`¶

Description: Run a governance health check. Verifies that .morphism/config.json, AGENTS.md, SSOT.md exist in the current project, that Python is available, and that governance scripts (scripts/verify_pipeline.py) are present. Exits with code 1 if any check fails.

Usage:

morphism doctor

Flags: None beyond global help flags.

Example:

morphism doctor

Expected output (passing):

  [+] .morphism/ config exists
  [+] AGENTS.md exists
  [+] SSOT.md exists
  [+] Python available
  [+] Governance scripts exist

All checks passed

Expected output (failing):

  [-] .morphism/ config exists
  [+] AGENTS.md exists
  ...
Some checks failed — run `morphism init` to set up

`morphism validate`¶

Description: Run the full governance validation pipeline. Executes three stages in order:

scripts/verify_pipeline.py — structural file checks
scripts/maturity_score.py --ci --threshold 0 — governance maturity score
Categorical loop via @morphism-systems/mcp-server (if installed) — computes kappa (κ), delta (δ), naturality, and writes a proof witness to .morphism/proofs/

If --format json is used, all output is a single JSON object. Exits with code 1 on validation failure.

Usage:

morphism validate [flags]

Flags:

Flag	Type	Default	Description
`--full`	boolean	false	Run full validation including categorical loop
`--commit <sha>`	string	HEAD	Git commit SHA to validate against
`--proof-dir <dir>`	string	`.morphism/proofs`	Directory for proof witness output
`--format <fmt>`	`text` \| `json`	`text`	Output format

Example:

morphism validate --format json

Expected output (text, passing):

κ = 0.0000 | δ = 0.0000
Maturity: converged | Converging: true
Violations: 0
Proof: .morphism/proofs/proof-2026-03-12T...json
Governance validation: PASS

Expected output (JSON):

{
  "passed": true,
  "kappa": 0.0,
  "delta": 0.0,
  "maturity_level": "converged",
  "maturity_score": 125,
  "converging": true,
  "violation_count": 0,
  "proof_path": ".morphism/proofs/proof-2026-03-12T....json",
  "summary": "All governance checks passed"
}

`morphism score`¶

Description: Compute the governance maturity score by running scripts/maturity_score.py --ci. Exits with code 1 if the score falls below the threshold.

Usage:

morphism score [flags]

Flags:

Flag	Type	Default	Description
`-t, --threshold <n>`	integer	`60`	Minimum score to pass

Example:

morphism score --threshold 100

Expected output:

Maturity score: 125/125
  [+] policy_coverage    25/25
  [+] ssot_atoms         20/20
  ...

`morphism status`¶

Description: Print a one-line governance summary: current maturity score, drift item count, and number of proof witnesses in .morphism/proofs/.

Usage:

morphism status

Flags: None beyond global help flags.

Example:

morphism status

Expected output:

Maturity: 125/125  |  Drift: 0 items  |  Proofs: 12

`morphism diff`¶

Description: Show governance files changed since a given git ref. Compares against HEAD~1 by default. Prints each changed file with a git diff --stat summary line, then runs the drift scanner to report current drift item count.

Usage:

morphism diff [flags]

Flags:

Flag	Type	Default	Description
`--since <ref>`	git ref	`HEAD~1`	Git ref to compare against

Example:

morphism diff --since main

Expected output:

Governance changes since main:

  docs/governance/roadmap.md
    roadmap.md | 4 +-

1 governance file(s) changed.
Current drift: 0 drift items

`morphism scaffold`¶

Description: Scaffold projects, packages, and governance files. Has four subcommands.

`morphism scaffold monorepo <name>`¶

Generate a full Morphism-governed monorepo directory at ./<name>/ with: package.json, turbo.json, tsconfig.json, governance files (AGENTS.md, SSOT.md, GUIDELINES.md, .morphism/config.json), app stub, shared package stub, CI workflow, and scripts/verify_pipeline.py.

morphism scaffold monorepo my-app

`morphism scaffold package <name>`¶

Add a new package to an existing monorepo. Creates packages/<name>/package.json, tsconfig.json, src/index.ts, and a test stub.

morphism scaffold package my-utils

`morphism scaffold governance`¶

Add governance files to an existing project: AGENTS.md, SSOT.md, GUIDELINES.md, .morphism/config.json, .github/workflows/governance.yml, .githooks/pre-commit, .githooks/commit-msg.

morphism scaffold governance

Next steps printed:

1. Run: git config core.hooksPath .githooks
2. Review AGENTS.md and customize invariants
3. Push to trigger governance CI checks

`morphism scaffold tier <tier>`¶

Generate tier-specific governance files for any project.

morphism scaffold tier 1 [flags]

Tiers:

Tier	Type	Files generated
`1`	Web Application (React/TypeScript)	`CLAUDE.md`, `GUIDELINES.md`, CI workflow, GitHub templates
`2`	Research / Python	`CLAUDE.md`, `GUIDELINES.md`, `AGENTS.md`, `CONTRIBUTING.md`, CI workflow, GitHub templates
`3`	Governance / Monorepo	`CLAUDE.md`, `GUIDELINES.md`, `AGENTS.md`, `CONTRIBUTING.md`, `.morphism/config.json`, CI workflow, GitHub templates

Flags:

Flag	Type	Default	Description
`-n, --name <name>`	string	directory name	Project name
`-i, --interactive`	boolean	false	Prompt for project-specific values (framework, domain, build system, etc.)
`--no-ci`	boolean	—	Skip CI workflow generation
`--no-github`	boolean	—	Skip GitHub issue/PR templates

Example:

morphism scaffold tier 2 --name my-research --interactive

`morphism scaffold legacy <template>`¶

Legacy scaffold templates for backward compatibility.

Templates: ts-project, py-project

morphism scaffold legacy ts-project

`morphism entropy`¶

Description: Measure and analyze Shannon entropy of text content or files. Has three subcommands. Uses the Python entropy backend (morphism.entropy.llm_entropy) when available, with a JavaScript fallback.

`morphism entropy measure <text>`¶

Measure Shannon entropy of a text string.

morphism entropy measure "hello world" [flags]

Flags:

Flag	Type	Default	Description
`--base <n>`	integer	`2`	Logarithm base (`2`=bits, `e`=nats, `10`=dits)
`--json`	boolean	false	Output as JSON

Expected output:

=== Entropy Measurement ===

Entropy: 2.846 bits
Classification: moderate
...
Visual: [###########---------]

`morphism entropy compare <text1> <text2>`¶

Compare entropy between two text strings.

morphism entropy compare "text one" "text two" [flags]

Flags:

Flag	Type	Default	Description
`--json`	boolean	false	Output as JSON

`morphism entropy report <files...>`¶

Generate an entropy report for one or more files.

morphism entropy report docs/governance/*.md [flags]

Flags:

Flag	Type	Default	Description
`--json`	boolean	false	Output as JSON
`-v, --verbose`	boolean	false	Include detailed per-artifact interpretations

Expected output:

=== Entropy Report ===

Analyzed 3 artifacts

Summary:
  Average entropy: 3.421
  Range: 2.846 - 4.012

Artifacts:
  docs/governance/MORPHISM.md    3.412  moderate  [##############------]
  ...

`morphism proof`¶

Description: Manage proof witnesses — cryptographic records of governance validation runs stored in .morphism/proofs/. Has two subcommands.

`morphism proof list`¶

Query proof witness history. Each witness records: timestamp, kappa value, maturity level, verdict, and commit SHA.

morphism proof list [flags]

Flags:

Flag	Type	Default	Description
`-n, --limit <n>`	integer	`10`	Maximum results to return
`--since <date>`	ISO date string	—	Filter witnesses from this date forward
`--json`	boolean	false	Output as JSON

Expected output:

Proof witnesses (3):
  kappa range: 0.0000 - 0.1234

  2026-03-12T10:00:00Z | k=0.0000 | converged | PASS @ 1178575
  2026-03-11T14:30:00Z | k=0.0500 | maturing | PASS @ 9999d90
  2026-03-10T09:15:00Z | k=0.1234 | maturing | PASS @ 6b58306

`morphism proof verify [file]`¶

Verify the SHA-256 signature integrity of proof witnesses. If file is omitted, verifies all witnesses in .morphism/proofs/. Exits with code 1 if any witness fails.

morphism proof verify [file] [flags]

Flags:

Flag	Type	Default	Description
`--json`	boolean	false	Output as JSON

Expected output:

Verifying 3 proof witnesses...

  [PASS] proof-2026-03-12T....json
  [PASS] proof-2026-03-11T....json
  [FAIL] proof-2026-03-10T....json
         Signature mismatch — witness may have been tampered with

2/3 witnesses FAILED verification.

`morphism policy`¶

Description: Manage governance policy packs — YAML files in policy-packs/ that define rules for the governance engine. Has two subcommands.

`morphism policy list`¶

List all policy packs discovered in the current project's policy-packs/ directory.

morphism policy list [flags]

Flags:

Flag	Type	Default	Description
`--json`	boolean	false	Output as JSON

Expected output:

Policy packs (2):

  core-governance v1.0.0 [strict]
    Enforces all 7 kernel invariants
    14 rules | policy-packs/core-governance.yml

  drift-prevention v0.2.0 [warn]
    Detects and flags governance drift
    6 rules | policy-packs/drift-prevention.yml

`morphism policy validate <file>`¶

Validate a policy pack YAML file against the policy pack schema. Exits with code 1 if invalid.

morphism policy validate policy-packs/core-governance.yml [flags]

Flags:

Flag	Type	Default	Description
`--json`	boolean	false	Output as JSON

Expected output (passing):

PASS: policy-packs/core-governance.yml is valid

Expected output (failing):

FAIL: policy-packs/draft.yml has 2 error(s):
  - Missing required field: name
  - Invalid mode: strict-plus (must be strict|warn|off)

CLI Reference¶

Global flags¶

Commands¶

morphism init¶

morphism doctor¶

morphism validate¶

morphism score¶

morphism status¶

morphism diff¶

morphism scaffold¶

morphism scaffold monorepo <name>¶

morphism scaffold package <name>¶

morphism scaffold governance¶

morphism scaffold tier <tier>¶

morphism scaffold legacy <template>¶

morphism entropy¶

morphism entropy measure <text>¶

morphism entropy compare <text1> <text2>¶

morphism entropy report <files...>¶

morphism proof¶

morphism proof list¶

morphism proof verify [file]¶

morphism policy¶

morphism policy list¶

morphism policy validate <file>¶

`morphism init`¶

`morphism doctor`¶

`morphism validate`¶

`morphism score`¶

`morphism status`¶

`morphism diff`¶

`morphism scaffold`¶

`morphism scaffold monorepo <name>`¶

`morphism scaffold package <name>`¶

`morphism scaffold governance`¶

`morphism scaffold tier <tier>`¶

`morphism scaffold legacy <template>`¶

`morphism entropy`¶

`morphism entropy measure <text>`¶

`morphism entropy compare <text1> <text2>`¶

`morphism entropy report <files...>`¶

`morphism proof`¶

`morphism proof list`¶

`morphism proof verify [file]`¶

`morphism policy`¶

`morphism policy list`¶

`morphism policy validate <file>`¶