Muse CLI — Three-Tier Architecture Reference

Muse CLI is organized into three formally separated tiers. Each tier has a distinct contract, audience, and stability guarantee.

┌──────────────────────────────────────────────────────────────────┐
│  Tier 3 — Semantic Porcelain                                     │
│  muse midi …   muse code …   muse coord …                       │
│  Domain-specific multidimensional commands                       │
├──────────────────────────────────────────────────────────────────┤
│  Tier 2 — Core Porcelain                                         │
│  muse init / commit / status / log / diff / show …              │
│  Human and agent VCS operations (domain-agnostic)               │
├──────────────────────────────────────────────────────────────────┤
│  Tier 1 — Plumbing                                               │
│  muse plumbing hash-object / cat-object / rev-parse …           │
│  Machine-readable, JSON-outputting, pipeable primitives          │
└──────────────────────────────────────────────────────────────────┘

Tier 1 — Low-level commands

Invoked as: muse <command> (no sub-namespace — agents reach these in one token)

Contract

Every low-level command:

• Outputs JSON by default — machine-stable schema, versioned, agent-parseable.
• Accepts --format text — human-readable fallback where meaningful.
• Never prompts — strictly non-interactive; safe for agent pipelines.
• Exit codes — 0 success, 1 user error (bad args, missing ref), 3 internal error.
• Pipeable — reads from stdin (unpack-objects) or writes to stdout (pack-objects, cat-object).
• Stable API — output schemas do not break across Muse versions.

These are the atoms from which porcelain commands are composed. They expose the raw engine directly, enabling MuseHub, agent orchestrators, CI pipelines, and shell scripts to interact with the store without going through the higher-level VCS logic.

Commands

JSON Output Schemas

hash-object

{
  "object_id": "<sha256-hex-64>",
  "stored": false
}

cat-object --format info

{
  "object_id": "<sha256-hex-64>",
  "present": true,
  "size_bytes": 1234
}

With --format raw (default): raw bytes written to stdout.

rev-parse

{
  "ref": "main",
  "commit_id": "<sha256-hex-64>"
}

Error (exit 1):

{
  "ref": "nonexistent",
  "commit_id": null,
  "error": "not found"
}

ls-files

{
  "commit_id": "<sha256>",
  "snapshot_id": "<sha256>",
  "file_count": 3,
  "files": [
    {"path": "tracks/drums.mid", "object_id": "<sha256>"},
    {"path": "tracks/bass.mid",  "object_id": "<sha256>"}
  ]
}

read-commit

Full CommitRecord JSON — see store.py for the complete schema. Key fields:

{
  "commit_id": "<sha256>",
  "repo_id": "<uuid>",
  "branch": "main",
  "snapshot_id": "<sha256>",
  "message": "Add verse melody",
  "committed_at": "2026-03-18T12:00:00+00:00",
  "parent_commit_id": "<sha256> | null",
  "parent2_commit_id": null,
  "author": "gabriel",
  "agent_id": "",
  "sem_ver_bump": "none"
}

read-snapshot

{
  "snapshot_id": "<sha256>",
  "created_at": "2026-03-18T12:00:00+00:00",
  "file_count": 3,
  "manifest": {
    "tracks/drums.mid": "<sha256>",
    "tracks/bass.mid":  "<sha256>"
  }
}

commit-tree

{"commit_id": "<sha256>"}

update-ref

{
  "branch": "main",
  "commit_id": "<sha256>",
  "previous": "<sha256> | null"
}

Delete (--delete):

{"branch": "todelete", "deleted": true}

commit-graph

{
  "tip": "<sha256>",
  "count": 42,
  "truncated": false,
  "commits": [
    {
      "commit_id": "<sha256>",
      "parent_commit_id": "<sha256> | null",
      "parent2_commit_id": null,
      "message": "Add verse melody",
      "branch": "main",
      "committed_at": "2026-03-18T12:00:00+00:00",
      "snapshot_id": "<sha256>",
      "author": "gabriel"
    }
  ]
}

pack-objects / unpack-objects

pack-objects writes a PackBundle JSON to stdout:

{
  "commits":   [{ ...CommitDict... }],
  "snapshots": [{ ...SnapshotDict... }],
  "objects":   [{"object_id": "<sha256>", "content_b64": "<base64>"}],
  "branch_heads": {"main": "<sha256>"}
}

unpack-objects reads a PackBundle from stdin and outputs:

{
  "commits_written":   12,
  "snapshots_written": 12,
  "objects_written":   47,
  "objects_skipped":   3
}

ls-remote --json

{
  "repo_id": "<uuid>",
  "domain": "midi",
  "default_branch": "main",
  "branches": {
    "main": "<sha256>",
    "dev":  "<sha256>"
  }
}

Tier 2 — Core Porcelain

Namespace: top-level muse <command>

These are the human and agent VCS commands — the interface most users interact with. They compose Tier 1 plumbing primitives into user-friendly workflows.

Tier 3 — Semantic Porcelain

Namespaces: muse midi …, muse code …, muse coord …

Domain-specific commands that interpret multidimensional state. These are impossible to implement in Git — they require awareness of the domain's semantic model (note events, symbol graphs, agent coordination).

muse midi … — MIDI Domain

Full reference: MIDI Domain Reference

Notation & Visualization

Pitch, Harmony & Scale

Rhythm & Dynamics

Structure & Voice Leading

History & Attribution

Multi-Agent Intelligence

Transformation

Invariants & Quality Gates

muse code … — Code Domain

muse coord … — Multi-Agent Coordination

Extending with New Domains

To add a new domain (e.g. muse genomics …):

1. Create muse/plugins/genomics/plugin.py implementing MuseDomainPlugin.
2. Create muse/cli/commands/genomics_*.py command modules.
3. Add a genomics_cli = typer.Typer(name="genomics", …) in muse/cli/app.py.
4. Register commands under genomics_cli and add cli.add_typer(genomics_cli, name="genomics").
5. Write tests under tests/ and docs under docs/reference/.

The core engine (muse/core/) is never modified for a new domain.