# Muse Low-level Commands Reference

Low-level commands are the machine-readable layer of the Muse CLI.
They output JSON, stream bytes without size limits, use predictable exit codes,
and compose cleanly in shell pipelines and agent scripts.

If you want to automate Muse — write a script, build an agent workflow, or
integrate Muse into another tool — these commands are the right entry point.
The higher-level porcelain commands (`muse commit`, `muse merge`, etc.) call
these internally.

These commands were previously namespaced under `muse plumbing <cmd>` and are
now top-level: `muse <cmd>`. No sub-namespace needed.

---

## Quick Index

| Command | Purpose |
|---|---|
| [`hash-object`](#hash-object) | Compute SHA-256 of a file; optionally store it |
| [`cat-object`](#cat-object) | Stream raw bytes or metadata for a stored object |
| [`verify-object`](#verify-object) | Re-hash stored objects to detect corruption |
| [`rev-parse`](#rev-parse) | Resolve branch name / HEAD / prefix → full commit ID |
| [`read-commit`](#read-commit) | Print full commit JSON record |
| [`read-snapshot`](#read-snapshot) | Print full snapshot JSON record |
| [`ls-files`](#ls-files) | List tracked files and their object IDs |
| [`commit-tree`](#commit-tree) | Create a commit from an existing snapshot |
| [`update-ref`](#update-ref) | Move or delete a branch ref |
| [`commit-graph`](#commit-graph) | BFS walk of the commit DAG |
| [`merge-base`](#merge-base) | Find the lowest common ancestor of two commits |
| [`snapshot-diff`](#snapshot-diff) | Diff two snapshots: added / modified / deleted |
| [`pack-objects`](#pack-objects) | Pack commits, snapshots, and objects into an MPack |
| [`unpack-objects`](#unpack-objects) | Apply an MPack to the local store |
| [`verify-pack`](#verify-pack) | Three-tier integrity check for an MPack |
| [`show-ref`](#show-ref) | List all branch refs and their commit IDs |
| [`symbolic-ref`](#symbolic-ref) | Read or write the HEAD symbolic reference |
| [`for-each-ref`](#for-each-ref) | Iterate refs with full commit metadata; sort and filter |
| [`name-rev`](#name-rev) | Map commit IDs to `<branch>~N` names |
| [`check-ref-format`](#check-ref-format) | Validate branch/ref names against naming rules |
| [`check-ignore`](#check-ignore) | Test whether paths match `.museignore` rules |
| [`check-attr`](#check-attr) | Query `.museattributes` for merge strategies |
| [`domain-info`](#domain-info) | Inspect the active domain plugin and its schema |
| [`ls-remote`](#ls-remote) | List refs on a remote without changing local state |

---

## The Plumbing Contract

Every plumbing command follows the same rules:

| Property | Guarantee |
|---|---|
| **Output** | Text (or binary, for `pack-objects`) by default; JSON with `--json` |
| **Exit 0** | Success — output is valid and complete |
| **Exit 1** | User error — bad input, ref not found, invalid ID |
| **Exit 3** | Internal error — I/O failure, integrity check failed |
| **Idempotent reads** | Reading commands never modify state |
| **Idempotent writes** | Writing the same object twice is a no-op |
| **Encoding** | All text I/O is UTF-8 |
| **Object IDs** | Always the canonical `sha256:<64 lowercase hex>` form |
| **Short flags** | Every flag has a `-x` short form |

Every command accepts a boolean `--json` / `-j` flag. **There is no
`--format` flag anywhere in the CLI** — flags are booleans, not
`choice`-style value flags. Passing `--json` switches output from plain text
(the default for most commands) to structured JSON; omitting it prints the
human-readable default shown in each command's "default output" example
below. Check each command's own section — some (`ls-remote`, `show-ref`,
`read-snapshot`, `verify-object`, `domain-info`, `symbolic-ref`,
`for-each-ref`, `name-rev`, `check-ref-format`, `check-ignore`, `check-attr`)
default to plain text and require `--json` for structured output, matching
`git`-style plumbing conventions.

JSON output is always printed to `stdout`.  When an error occurs in `--json`
mode, the error is emitted as a `{"error": "..."}` (or `{"status": "error",
"error": "..."}`) object on `stdout` — not `stderr` — so scripts that parse
`stdout` can detect the failure without inspecting exit codes separately.

Every `--json` response is wrapped in a standard envelope carrying
`muse_version`, `schema`, `exit_code`, `duration_ms`, `timestamp`, and
`warnings`, in addition to the command-specific fields shown in each example
below. The examples in this document omit the envelope for brevity and show
only the command-specific fields — the envelope keys are always present
alongside them. For example, `muse rev-parse HEAD --json` actually prints:

```json
{"muse_version": "0.2.1rc4", "schema": 1, "exit_code": 0, "duration_ms": 0.9,
 "timestamp": "2026-03-18T12:00:00.000Z", "warnings": [],
 "ref": "HEAD", "commit_id": "sha256:a3f2...c8d1"}
```

---

## Command Reference

<a id="hash-object"></a>
### `hash-object` — compute a content ID

```
muse hash-object <file> [--stdin] [-w] [-j]
```

Computes the SHA-256 content address of a file or `stdin` stream.  Identical
bytes always produce the same ID; this is how Muse deduplicates storage.
With `--write` (`-w`) the object is also stored in `.muse/objects/` so it can
be referenced by future snapshots and commits.  The file is streamed at
64 KiB at a time — arbitrarily large blobs never spike memory.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--stdin` | — | off | Read content from stdin instead of a file path |
| `--write` | `-w` | off | Store the object after hashing |
| `--json` | `-j` | off | Emit machine-readable JSON (default: plain text object ID) |

**Output — default (plain text)**

```
sha256:a3f2...c8d1
```

**Output — `--json`**

```json
{"object_id": "sha256:a3f2...c8d1", "stored": false, "size_bytes": 5}
```

`stored` is `true` only when `--write` is passed and the object was not
already in the store.

**Exit codes:** 0 success · 1 path not found or is a directory · 3 I/O write error or integrity check failed

---

<a id="cat-object"></a>
### `cat-object` — read a stored object

```
muse cat-object <object-id> [-j] [--inline]
muse cat-object --batch | --batch-check
```

Reads a content-addressed object from `.muse/objects/`.  By default the raw
bytes are streamed to `stdout` at 64 KiB at a time — pipe to a file, another
process, or a network socket without any size ceiling.  With `--json` a JSON
metadata summary is printed instead of the content.

Object IDs must be given in the canonical `sha256:<64-hex>` form — bare hex
is rejected.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit JSON metadata instead of raw bytes |
| `--inline` | — | off | With `--json`, embed the object content as base64 in `content_b64` (requires `--json`) |
| `--batch` | — | off | Batch mode: read object IDs from stdin, one per line; emit `<oid> blob <size>\n<content>\n` per object (`<oid> missing\n` for absent/invalid ones) |
| `--batch-check` | — | off | Like `--batch` but header-only — no content bytes |

**Output — default (raw bytes)**

```
hello
```

**Output — `--json`**

```json
{"object_id": "sha256:a3f2...c8d1", "present": true, "size_bytes": 4096}
```

With `--inline`:

```json
{"object_id": "sha256:a3f2...c8d1", "present": true, "size_bytes": 5,
 "content_b64": "aGVsbG8="}
```

When the object is absent and `--json` is used, `present` is `false` and
`size_bytes` is `0` (exit 1).  When raw mode is used and the object is
absent, the error goes to `stderr` (exit 1).

**Exit codes:** 0 found · 1 not found or invalid ID format · 3 I/O read error. Batch mode (`--batch`/`--batch-check`) always exits 0 — missing objects are reported inline, not as failures.

---

<a id="rev-parse"></a>
### `rev-parse` — resolve a ref to a commit ID

```
muse rev-parse <ref> [--abbrev-ref] [-j]
```

Resolves a branch name, `HEAD`, or an abbreviated SHA prefix to the full
64-character commit ID.  Use this to canonicalise any ref before passing it to
other commands.

**Arguments**

| Argument | Description |
|---|---|
| `<ref>` | Branch name, `HEAD`, full commit ID, or unique prefix |

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--abbrev-ref` | — | off | Resolve to the branch name instead of the commit ID |
| `--json` | `-j` | off | Emit machine-readable JSON (default: plain text commit ID) |

**Output — default (plain text)**

```
sha256:a3f2...c8d1
```

**Output — `--json`**

```json
{"ref": "main", "commit_id": "sha256:a3f2...c8d1"}
```

**Output — `--abbrev-ref`**

```json
{"ref": "HEAD", "branch": "main"}
```
Text mode with `--abbrev-ref` prints just `main`.

Ambiguous or unresolvable prefixes return a JSON error object on `stdout`
(exit 1): `{"ref": "...", "commit_id": null, "error": "not found"}`.

**Exit codes:** 0 resolved · 1 not found, ambiguous, or empty ref

---

<a id="ls-files"></a>
### `ls-files` — list files in a snapshot

```
muse ls-files [--commit <id>] [--path-prefix <prefix>] [-j]
```

Lists every file tracked in a commit's snapshot together with its content
object ID.  Defaults to the HEAD commit of the current branch.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--commit` | `-c` | HEAD | Commit ID to inspect |
| `--path-prefix` | `-p` | — | Only list files whose path starts with this prefix |
| `--json` | `-j` | off | Emit machine-readable JSON (default: tab-separated text) |

**Output — default (tab-separated, suitable for `awk` / `cut`)**

```
sha256:c1d2...a3b4	tracks/bass.mid
sha256:e5f6...b7c8	tracks/drums.mid
sha256:09ab...cd10	tracks/piano.mid
```

**Output — `--json`**

```json
{
  "status":      "ok",
  "error":       "",
  "commit_id":   "sha256:a3f2...c8d1",
  "snapshot_id": "sha256:b7e4...f912",
  "branch":      "main",
  "path_prefix": null,
  "file_count":  3,
  "files": [
    {"path": "tracks/bass.mid",  "object_id": "sha256:c1d2...a3b4"},
    {"path": "tracks/drums.mid", "object_id": "sha256:e5f6...b7c8"},
    {"path": "tracks/piano.mid", "object_id": "sha256:09ab...cd10"}
  ]
}
```

All keys are always present so agents can read them without `dict.get`
guards. `"branch"` is `null` when `--commit` is given explicitly (no branch
resolution occurs). `"path_prefix"` is `null` when no `--path-prefix` filter
was applied. Files are sorted by path.

On error, `--json` mode emits `{"status": "error", "error": "...", "exit_code": 1}` to `stdout`.

**Exit codes:** 0 listed · 1 commit or snapshot not found, or invalid argument

---

<a id="read-commit"></a>
### `read-commit` — print full commit metadata

```
muse read-commit <commit-id> [--fields FIELD,...] [-j]
```

Emits the complete JSON record for a commit.  Accepts a full 64-character ID
or a unique prefix. Default output (no `--json`) is a compact one-line
summary; the full structured record requires `--json`.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--fields` | — | (all) | Comma-separated list of fields to include in JSON output — reduces response size for agent pipelines |
| `--json` | `-j` | off | Emit machine-readable JSON (default: compact one-line text) |

**Output — default (plain text)**

```
sha256:a3f2...c8d1  main  gabriel  2026-03-21T12:00:00+00:00  Add verse melody
```

**Output — `--json`**

```json
{
  "commit_id": "sha256:a3f2...c8d1",
  "branch": "main",
  "snapshot_id": "sha256:b7e4...f912",
  "message": "Add verse melody",
  "committed_at": "2026-03-18T12:00:00+00:00",
  "parent_commit_id": "sha256:ff01...23ab",
  "parent2_commit_id": null,
  "author": "gabriel",
  "agent_id": "",
  "model_id": "",
  "toolchain_id": "",
  "sem_ver_bump": "none",
  "breaking_changes": [],
  "reviewed_by": [],
  "test_runs": 0
}
```

Use `--fields` to trim the response, e.g.
`muse read-commit <id> --fields commit_id,branch,message,committed_at --json`.

Error conditions always produce JSON on `stdout` so scripts can parse them
without inspecting `stderr`.

**Exit codes:** 0 found · 1 not found, ambiguous prefix, or invalid ID format

---

<a id="read-snapshot"></a>
### `read-snapshot` — print full snapshot metadata

```
muse read-snapshot <snapshot-id> [--no-manifest] [--path-prefix <prefix>] [-j]
```

Emits the complete JSON record for a snapshot.  Every commit references exactly
one snapshot.  Use `ls-files --commit <id>` if you want to look up a snapshot
from a commit ID rather than the snapshot ID directly.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--no-manifest` | — | off | Omit the file manifest, returning only `snapshot_id`, `created_at`, `file_count`. Only valid with `--json` |
| `--path-prefix` | `-p` | — | Filter the manifest to paths starting with this prefix |
| `--json` | `-j` | off | Emit machine-readable JSON (default: compact one-line text) |

**Output — default (plain text)**

```
sha256:b7e4...f912  3 files  2026-03-21T12:00:00+00:00
```

**Output — `--json`**

```json
{
  "snapshot_id": "sha256:b7e4...f912",
  "created_at": "2026-03-18T12:00:00+00:00",
  "file_count": 3,
  "manifest": {
    "tracks/bass.mid":  "sha256:c1d2...a3b4",
    "tracks/drums.mid": "sha256:e5f6...b7c8",
    "tracks/piano.mid": "sha256:09ab...cd10"
  }
}
```

With `--no-manifest --json`:

```json
{"snapshot_id": "sha256:b7e4...f912", "created_at": "2026-03-18T12:00:00+00:00", "file_count": 3}
```

**Exit codes:** 0 found · 1 not found, invalid ID format, or `--no-manifest` used without `--json`

---

<a id="commit-tree"></a>
### `commit-tree` — create a commit from a snapshot ID

```
muse commit-tree -s <snapshot-id> [-p <parent-id>]... [-m <message>] [-a <author>] [-b <branch>] [--agent-id <id>] [--model-id <id>] [--toolchain-id <id>] [-j]
```

Low-level commit creation.  The snapshot must already exist in the store.  Both
the snapshot ID and any parent IDs are validated as proper 64-character SHA-256
hex strings before any I/O is attempted.  Use `--parent` / `-p` once for a
linear commit and twice for a merge commit (at most two parents are
supported).  The commit is written to `.muse/commits/` but **no branch ref is
updated** — use `update-ref` to advance a branch to the new commit.

**Flags**

| Flag | Short | Required | Description |
|---|---|---|---|
| `--snapshot` | `-s` | ✅ | SHA-256 snapshot ID |
| `--parent` | `-p` | — | Parent commit ID (repeat once for merges) |
| `--message` | `-m` | — | Commit message |
| `--author` | `-a` | — | Author name |
| `--branch` | `-b` | — | Branch name to record (default: current branch) |
| `--agent-id` | — | — | Stable agent identifier (e.g. `counterpoint-bot`) |
| `--model-id` | — | — | Model identifier (e.g. `claude-opus-4`); empty for human authors |
| `--toolchain-id` | — | — | Toolchain that produced this commit (e.g. `cursor-agent-v2`) |
| `--json` | `-j` | — | Emit machine-readable JSON (default: bare commit ID as text) |

**Output — default (plain text)**

```
sha256:a3f2...c8d1
```

**Output — `--json`**

```json
{
  "commit_id":          "sha256:a3f2...c8d1",
  "snapshot_id":        "sha256:b7e4...f912",
  "branch":             "main",
  "message":            "feat: add melody",
  "committed_at":       "2026-03-18T12:00:00+00:00",
  "author":             "gabriel",
  "agent_id":           "counterpoint-bot",
  "model_id":           "claude-opus-4",
  "toolchain_id":       "cursor-agent-v2",
  "parent_commit_id":   "sha256:ff01...23ab",
  "parent2_commit_id":  null
}
```

The text form is ideal for shell pipelines where you want to capture the ID
directly without a `jq` call: `NEW=$(muse commit-tree -s "$SNAP" -m "msg")`.
Agents should always pass `--agent-id` / `--model-id` (and `--toolchain-id`
where applicable) so their identity is auditable in the resulting commit.

**Exit codes:** 0 commit written · 1 snapshot or parent not found, invalid ID format, or `repo.json` unreadable · 3 write failure

---

<a id="update-ref"></a>
### `update-ref` — move a branch to a commit

```
muse update-ref <branch> <commit-id> [--no-verify] [--old-value <commit-id>] [-j]
muse update-ref <branch> --delete [-j]
```

Directly writes (or deletes) a branch reference file under `.muse/refs/heads/`.
The branch name is validated with the same rules as `check-ref-format` before
any file is written — path-traversal via crafted branch names is not possible.
The commit ID format is always validated regardless of `--no-verify`, so a
malformed ID can never corrupt the ref file.

By default, the commit must already exist in the local store (`--verify` is on);
pass `--no-verify` to write the ref before the commit is stored — useful after
an `unpack-objects` pipeline where objects arrive in dependency order.

Use `--old-value` for compare-and-swap semantics in multi-agent environments:
the update succeeds only if the current ref value matches the expected value.
Pass `--old-value null` to require that the ref does not currently exist.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--delete` | `-d` | off | Delete the branch ref instead of updating it |
| `--no-verify` | — | off (verify is on) | Skip verifying the commit exists in the store before updating |
| `--old-value` | — | — | Compare-and-swap guard: only update if the current ref matches this commit ID (`null` = ref must not exist) |
| `--json` | `-j` | off | Emit machine-readable JSON (default: silent on success) |

**Output — default, update or delete (silent on success)**

Nothing is printed; the command exits 0.  This mirrors `git update-ref`,
making it drop-in compatible with shell scripts that use exit code only.

**Output — `--json`, update**

```json
{"branch": "main", "commit_id": "sha256:a3f2...c8d1", "previous": "sha256:ff01...23ab"}
```

`previous` is `null` when the branch had no prior commit.

**Output — `--json`, delete**

```json
{"branch": "feat/x", "deleted": true}
```

CAS failures include the conflicting values:

```json
{"error": "cas_mismatch", "message": "CAS mismatch: ...",
 "current": "sha256:...", "expected": "sha256:..."}
```

**Exit codes:** 0 done · 1 commit not in store (with verify on), invalid branch or commit ID, `--delete` on non-existent ref, or CAS mismatch · 3 file write failure

---

<a id="commit-graph"></a>
### `commit-graph` — emit the commit DAG

```
muse commit-graph [--tip <id>] [--stop-at <id>] [-n <max>] [-c] [-1] [-a] [-j]
```

Performs a BFS walk from a tip commit (defaulting to HEAD), following both
`parent_commit_id` and `parent2_commit_id` pointers.  Returns every reachable
commit.  Useful for building visualisations, computing reachability sets, or
finding the commits on a branch since it diverged from another.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--tip` | — | HEAD | Commit to start from |
| `--stop-at` | — | — | Stop BFS at this commit (exclusive) |
| `--max` | `-n` | 10 000 | Maximum commits to traverse |
| `--count` | `-c` | off | Emit only the integer count, not the full node list |
| `--first-parent` | `-1` | off | Follow only first-parent links — linear history, no merge parents |
| `--ancestry-path` | `-a` | off | With `--stop-at`: restrict to commits on the direct path between tip and stop-at |
| `--json` | `-j` | off | Emit machine-readable JSON (default: one commit ID per line, prefixed with a `# TRUNCATED` comment line if `--max` cut the walk short) |

**Output — default (plain text)**

```
sha256:a3f2...c8d1
sha256:ff01...23ab
```

**Output — `--json`**

```json
{
  "tip": "sha256:a3f2...c8d1",
  "count": 42,
  "truncated": false,
  "commits": [
    {
      "commit_id":        "sha256:a3f2...c8d1",
      "parent_commit_id": "sha256:ff01...23ab",
      "parent2_commit_id": null,
      "message":          "Add verse melody",
      "branch":           "main",
      "committed_at":     "2026-03-18T12:00:00+00:00",
      "snapshot_id":      "sha256:b7e4...f912",
      "author":           "gabriel",
      "agent_id":         "claude-code",
      "model_id":         "claude-sonnet-4-6",
      "sem_ver_bump":     "minor",
      "breaking_changes": []
    }
  ]
}
```

`truncated` is `true` when the graph was cut off by `--max`.

**Output — `--count --json`**

```json
{"tip": "sha256:a3f2...c8d1", "count": 42, "truncated": false}
```

`--count` suppresses the `commits` array entirely, making it suitable for fast
cardinality checks without loading commit metadata.

**Examples**

Commits on a feature branch since it diverged from `main`:

```sh
BASE=$(muse merge-base feat/x main)
muse commit-graph --tip feat/x --stop-at "$BASE"
```

Count commits in a feature branch:

```sh
muse commit-graph \
  --tip "$(muse rev-parse feat/x)" \
  --stop-at "$(muse merge-base feat/x dev)" \
  --count --json
```

Linear history only (skip merge parents):

```sh
muse commit-graph --first-parent
```

**Exit codes:** 0 graph emitted · 1 tip commit not found, or `--ancestry-path` without `--stop-at`

---

<a id="pack-objects"></a>
### `pack-objects` — pack commits for transport

```
muse pack-objects <want>... [--have <id>...] [--dry-run] [-j]
```

Collects a set of commits — and all their referenced snapshots and objects —
into a single `MPack` (msgpack binary) written to `stdout`.  Pass `--have` to
tell the packer which commits the receiver already has; objects reachable
only from `--have` ancestors are excluded, minimising transfer size.

`<want>` may be a full commit ID or `HEAD`.

**Flags**

| Flag | Short | Description |
|---|---|---|
| `--have` | — | Commits the receiver already has (repeat for multiple) |
| `--dry-run` | `-n` | Print a JSON summary of what would be packed instead of writing binary msgpack |
| `--json` | `-j` | Shorthand equivalent used with `--dry-run` to emit the JSON summary |

**Output — default** — an `MPack` msgpack binary (pipe to a file or `unpack-objects`)

**Output — `--dry-run`**

```json
{"want": ["sha256:a3f2...c8d1"], "have": [], "commits": 3, "snapshots": 3, "blobs": 12, "object_bytes": 40960}
```

`object_bytes` is the total uncompressed byte size of all object payloads in
the pack — use it to decide whether to buffer the full mpack in memory or
stream it directly to the remote.

**Exit codes:** 0 pack written (or dry-run summary printed) · 1 a wanted commit not found or HEAD has no commits · 3 I/O error reading from the local store

---

<a id="unpack-objects"></a>
### `unpack-objects` — apply an mpack to the local store

```
cat pack.muse | muse unpack-objects [-j]
muse pack-objects HEAD | muse unpack-objects
```

Reads an `MPack` from `stdin` and writes its commits, snapshots, blobs, and
tags into `.muse/`.  Idempotent: objects already present in the store are
silently skipped.  Partial packs from interrupted transfers are safe to
re-apply.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable summary) |

**Output — default (plain text)**

```
Wrote 12 commits, 12 snapshots, 47 blobs (3 skipped), 2 tags.
```

**Output — `--json`**

```json
{
  "commits_written":   12,
  "snapshots_written": 12,
  "blobs_written":     47,
  "blobs_skipped":      3,
  "tags_written":       2
}
```

**Exit codes:** 0 unpacked (all objects stored) · 1 invalid or malformed msgpack input, or input is not a top-level map · 3 write failure

---

<a id="ls-remote"></a>
### `ls-remote` — list refs on a remote

```
muse ls-remote [<remote-or-url>] [-j]
```

Contacts a remote and lists every branch HEAD without altering local state.
The `<remote-or-url>` argument is either a remote name configured with
`muse remote add` (defaults to `origin`) or a full `https://` URL.

**Flags**

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: tab-separated text) |

**Output — default (plain text)**

One line per branch, tab-separated.  The default branch is marked with ` *`.

```
sha256:a3f2...c8d1	main *
sha256:b7e4...f912	feat/experiment
```

**Output — `--json`**

```json
{
  "status":         "ok",
  "error":          "",
  "repo_id":        "sha256:550e8400...",
  "domain":         "midi",
  "default_branch": "main",
  "branches": {
    "main":             "sha256:a3f2...c8d1",
    "feat/experiment":  "sha256:b7e4...f912"
  },
  "remote":         "origin",
  "url":            "https://musehub.ai/org/repo"
}
```

All keys are always present so agents can read them without `dict.get`
guards. `"remote"` is `null` when the caller passed a full URL directly
instead of a configured remote name. Branch commit IDs are always
`sha256:`-prefixed regardless of what the remote returns.

**Exit codes:** 0 remote contacted · 1 remote not configured or URL invalid · 3 transport error (network, HTTP error)

---

## Composability Patterns

### Export a history range

```sh
# All commits on feat/x that are not on main
BASE=$(muse rev-parse main)
TIP=$(muse rev-parse feat/x)
muse commit-graph --tip "$TIP" --stop-at "$BASE"
```

### Ship commits between two machines

```sh
# On the sender — pack everything the receiver doesn't have
HAVE=$(muse ls-remote origin | awk '{print "--have " $1}' | tr '\n' ' ')
muse pack-objects HEAD $HAVE > bundle.muse

# On the receiver
cat bundle.muse | muse unpack-objects
muse update-ref main <commit-id>
```

### Verify a stored object

```sh
ID=$(muse hash-object tracks/drums.mid)
muse cat-object "$ID" --json
```

### Inspect what changed in the last commit

```sh
muse read-commit "$(muse rev-parse HEAD)" --json | \
  python3 -c "import sys, json; d=json.load(sys.stdin); print(d['message'])"
```

### Script a bare commit (advanced)

```sh
# 1. Hash and store the files
OID=$(muse hash-object -w tracks/drums.mid)

# 2. Build a snapshot manifest and write it (via muse commit is easier,
#    but for full control use commit-tree after writing the snapshot)
SNAP=$(muse rev-parse HEAD | \
  xargs -I{} muse read-commit {} --json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['snapshot_id'])")

# 3. Create a commit on top of HEAD
PARENT=$(muse rev-parse HEAD)
NEW=$(muse commit-tree -s "$SNAP" -p "$PARENT" -m "scripted commit" --json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['commit_id'])")

# 4. Advance the branch
muse update-ref main "$NEW"
```

---

<a id="merge-base"></a>
### `merge-base` — find the common ancestor of two commits

Find the lowest common ancestor of two commits — the point at which two
branches diverged.

```sh
muse merge-base <commit-a> <commit-b> [-j]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: plain text commit ID) |

Arguments accept full SHA-256 commit IDs, branch names, or `HEAD`.

**Default output (plain text):**

```
sha256:<sha256>
```

**`--json` output:**

```json
{
  "commit_a":   "sha256:<sha256>",
  "commit_b":   "sha256:<sha256>",
  "merge_base": "sha256:<sha256>"
}
```

When no common ancestor exists, `merge_base` is `null` and `error` is set.

| Exit | Meaning |
|---|---|
| 0 | Result computed (check `merge_base` for null vs. found) |
| 1 | A commit ID or ref cannot be resolved |
| 3 | DAG walk failed |

---

<a id="snapshot-diff"></a>
### `snapshot-diff` — diff two snapshot manifests

Compare two snapshots and categorise every changed path as added, modified,
or deleted.

```sh
muse snapshot-diff <ref-a> <ref-b> [-j] [-s] [--raw] [--only CATEGORY] [--path-prefix PREFIX]
muse snapshot-diff --stdin [-j]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit JSON output (default: human-readable text) |
| `--stat` | `-s` | off | Append a summary line in text mode |
| `--raw` | — | off | Include object IDs in text-format output (no effect on JSON, which always includes them) |
| `--only` | — | — | Restrict output to one category: `added`, `modified`, or `deleted` |
| `--path-prefix` | — | — | Filter the diff to paths starting with this prefix |
| `--stdin` | — | off | Batch mode: read `<ref-a> <ref-b>` pairs from stdin, one per line |

Arguments accept snapshot IDs, commit IDs, branch names, or `HEAD`.

**Default output (text):**

```
A  new.mid
M  main.mid
D  old.mid
```

With `--raw`:

```
A  sha256:<oid_b>  new.mid
M  sha256:<oid_a>  sha256:<oid_b>  main.mid
D  sha256:<oid_a>  old.mid
```

**`--json` output:**

```json
{
  "snapshot_a":     "sha256:<sha256>",
  "snapshot_b":     "sha256:<sha256>",
  "added":          [{"path": "new.mid",  "object_id": "sha256:<sha256>"}],
  "modified":       [{"path": "main.mid", "object_id_a": "sha256:<sha256>", "object_id_b": "sha256:<sha256>"}],
  "deleted":        [{"path": "old.mid",  "object_id": "sha256:<sha256>"}],
  "added_count":    1,
  "modified_count": 1,
  "deleted_count":  1,
  "total_changes":  3
}
```

`--only` restricts which category is populated (the other two are emitted as
empty arrays in JSON mode, or simply not printed in text mode). `--path-prefix`
is applied before `--only`, and counts/`total_changes` reflect the filtered
view.

| Exit | Meaning |
|---|---|
| 0 | Diff computed (zero changes is a valid result) |
| 1 | Ref cannot be resolved, or bad `--only` value |
| 3 | I/O error reading snapshot records |

Batch mode (`--stdin`) always exits 0; individual pair errors are reported inline.

---

<a id="domain-info"></a>
### `domain-info` — inspect the active domain plugin

Inspect the domain plugin active for this repository — its name, class,
optional protocol capabilities, and full structural schema.

```sh
muse domain-info [-j] [-a] [--domain DOMAIN] [--capabilities-only]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--all-domains` | `-a` | off | List every registered domain; no repo required |
| `--domain` | — | — | Inspect a specific domain by name without requiring an active repo |
| `--capabilities-only` | — | off | Emit only the capabilities dict |

**Default output (text):**

```
Domain:       midi
Plugin:       MidiPlugin
Merge mode:   three_way
Capabilities: addressed_merge
```

**`--json` output:**

```json
{
  "domain":       "midi",
  "plugin_class": "MidiPlugin",
  "capabilities": {
    "addressed_merge": true,
    "crdt":             false,
    "harmony":          false
  },
  "schema": {
    "domain": "midi", "merge_mode": "three_way",
    "dimensions": [...], "top_level": {...}
  },
  "registered_domains": ["bitcoin", "code", "midi", "scaffold"]
}
```

| Exit | Meaning |
|---|---|
| 0 | Domain resolved and schema emitted |
| 1 | No repository found, or domain not registered |
| 3 | Plugin raised an error computing its schema |

---

<a id="show-ref"></a>
### `show-ref` — list all branch refs

List all branch refs and the commit IDs they point to.

```sh
muse show-ref [-j] [-p PATTERN] [-H] [-v REF] [--count]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--pattern` | `-p` | `""` | fnmatch glob to filter ref names |
| `--head` | `-H` | off | Print only HEAD ref and commit ID |
| `--verify` | `-v` | `""` | Silent existence check — exit 0 if found, 1 if not |
| `--count` | — | off | Emit only the branch count |

**Default output (text):**

```
sha256:<sha256>  refs/heads/dev
* sha256:<sha256>  refs/heads/main  (HEAD)
```

**`--json` output:**

```json
{
  "refs": [
    {"ref": "refs/heads/dev",  "commit_id": "sha256:<sha256>"},
    {"ref": "refs/heads/main", "commit_id": "sha256:<sha256>"}
  ],
  "head":  {"ref": "refs/heads/main", "branch": "main", "commit_id": "sha256:<sha256>"},
  "count": 2
}
```

Use `--verify` in shell conditionals:

```sh
muse show-ref --verify refs/heads/my-branch && echo "branch exists"
```

| Exit | Meaning |
|---|---|
| 0 | Refs enumerated (or `--verify` ref exists) |
| 1 | `--verify` ref absent |
| 3 | I/O error reading refs directory |

---

<a id="check-ignore"></a>
### `check-ignore` — test whether paths are excluded by `.museignore`

Test whether workspace paths are excluded by `.museignore` rules.

```sh
muse check-ignore <path>... [-j] [-q] [-V] [--stdin] [--patterns-only] [--ignored-only]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--quiet` | `-q` | off | No output; exit 0 if all ignored, 1 otherwise |
| `--verbose` | `-V` | off | Include matching pattern in text output (JSON always includes it) |
| `--stdin` | — | off | Read additional paths from stdin, one per line |
| `--patterns-only` | — | off | Emit the resolved pattern list and exit; no path arguments needed |
| `--ignored-only` | — | off | Show only paths that are ignored |

**Default output (text):**

```
ignored  build/output.bin  [build/]
ok       tracks/dr.mid
```

**`--json` output:**

```json
{
  "domain":          "midi",
  "patterns_loaded": 4,
  "summary": {"total": 2, "ignored": 1, "not_ignored": 1},
  "results": [
    {"path": "build/out.bin", "ignored": true,  "matching_pattern": "build/"},
    {"path": "tracks/dr.mid", "ignored": false, "matching_pattern": null}
  ]
}
```

With `--patterns-only`:

```json
{"domain": "midi", "patterns_loaded": 3, "patterns": ["build/", "*.bin", "!tracks/*.mid"]}
```

Last-match-wins: a negation rule (`!important.mid`) can un-ignore a path
matched by an earlier rule.

| Exit | Meaning |
|---|---|
| 0 | Results emitted (or `--quiet` with all ignored) |
| 1 | `--quiet` with any non-ignored path; missing args; `--ignored-only` combined with `--patterns-only` or `--quiet` |
| 3 | I/O or TOML parse error reading `.museignore` |

---

<a id="check-attr"></a>
### `check-attr` — query merge-strategy attributes for paths

Query merge-strategy attributes for workspace paths from `.museattributes`.

```sh
muse check-attr <path>... [-j] [-d DIMENSION] [-A] [--stdin] [--rules-only] [--unmatched-only]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--dimension` | `-d` | `*` | Domain axis to query (e.g. `notes`, `tempo`) |
| `--all-rules` | `-A` | off | Return every matching rule, not just first-match |
| `--stdin` | — | off | Read additional paths from stdin, one per line |
| `--rules-only` | — | off | Emit the loaded rule list without testing any paths |
| `--unmatched-only` | — | off | Show only paths with no matching rule (`strategy=auto`) |

**`--json` output (default: first-match):**

```json
{
  "domain":       "midi",
  "rules_loaded": 3,
  "dimension":    "*",
  "summary": {"total": 2, "matched": 1, "unmatched": 1, "by_strategy": {"ours": 1, "auto": 1}},
  "results": [
    {
      "path":      "drums/kit.mid",
      "dimension": "*",
      "strategy":  "ours",
      "rule": {"path_pattern": "drums/*", "strategy": "ours", "priority": 10, ...}
    }
  ]
}
```

When no rule matches, `strategy` is `"auto"` and `rule` is `null`.

| Exit | Meaning |
|---|---|
| 0 | Attributes resolved and emitted |
| 1 | Missing args; `--unmatched-only` combined with `--rules-only` |
| 3 | TOML parse error in `.museattributes` |

---

<a id="verify-object"></a>
### `verify-object` — re-hash stored objects to detect corruption

Re-hash stored objects to detect silent data corruption.

```sh
muse verify-object <object-id>... [-j] [-q] [--all] [--stdin] [--fail-fast]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--quiet` | `-q` | off | No output; exit 0 if all OK, 1 otherwise |
| `--all` | `-a` | off | Verify every object in the store — the fsck equivalent |
| `--stdin` | — | off | Read additional object IDs from stdin, one per line |
| `--fail-fast` | — | off | Stop after the first failed object and exit 1 immediately |

Objects are streamed in 64 KiB chunks — safe for very large blobs.

**Default output (text):**

```
OK    sha256:<sha256>  (4096 bytes)
FAIL  sha256:<sha256>  object not found in store
---
Checked: 2  Failed: 1
```

**`--json` output:**

```json
{
  "results": [
    {"object_id": "sha256:<sha256>", "ok": true,  "size_bytes": 4096, "error": null},
    {"object_id": "sha256:<sha256>", "ok": false, "size_bytes": null,
     "error": "object not found in store"}
  ],
  "all_ok":  false,
  "checked": 2,
  "failed":  1
}
```

Compose with `show-ref` to verify every commit in a repo:

```bash
muse show-ref --json \
  | jq -r '.refs[].commit_id' \
  | xargs muse verify-object
```

| Exit | Meaning |
|---|---|
| 0 | All objects verified successfully |
| 1 | One or more objects failed; object not found; bad args |
| 3 | Unexpected I/O error (disk read failure) |

---

<a id="symbolic-ref"></a>
### `symbolic-ref` — read or write HEAD's symbolic reference

In Muse, HEAD is normally a symbolic reference — it points to a branch — but
can also be detached, pointing directly at a commit.  `symbolic-ref` reads
which branch HEAD tracks or, with `--set`, points HEAD at a different branch.

```sh
# Read mode
muse symbolic-ref HEAD [-j] [--short]

# Write mode
muse symbolic-ref HEAD --set <branch> [--create-branch] [-j]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--set` | `-s` | `""` | Branch name to point HEAD at |
| `--create-branch` | — | off | With `--set`, create the branch pointer even if it has no commits yet |
| `--short` | `-S` | off | Emit branch name only (not the full `refs/heads/…` path) |
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |

**Default output (text, read mode):**

```
refs/heads/main
```
With `--short`: `main`.

**`--json` output (read mode, normal branch HEAD):**

```json
{
  "ref":             "HEAD",
  "symbolic_target": "refs/heads/main",
  "branch":          "main",
  "commit_id":       "sha256:<sha256>",
  "detached":        false
}
```

**`--json` output (read mode, detached HEAD):**

```json
{
  "ref":             "HEAD",
  "symbolic_target": null,
  "branch":          null,
  "commit_id":       "sha256:<sha256>",
  "detached":        true
}
```

`commit_id` is `null` when the branch has no commits yet. `--set` without
`--create-branch` requires the target branch to already exist.

| Exit | Meaning |
|---|---|
| 0 | Ref read or written |
| 1 | `--set` target branch does not exist (without `--create-branch`); unsupported ref name; invalid branch name |
| 3 | I/O error reading or writing HEAD |

---

<a id="for-each-ref"></a>
### `for-each-ref` — iterate all refs with rich commit metadata

Enumerates every branch ref together with the full commit metadata it points to.
Supports sorting by any commit field and glob-pattern filtering, making it
ideal for agent pipelines that need to slice the ref list without post-processing.

```sh
muse for-each-ref [-p <pattern>] [-s <field>] [-d] [--count <count>] [--no-commits] [-j]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--pattern` | `-p` | `""` | fnmatch glob on the full ref name, e.g. `refs/heads/feat/*` |
| `--sort` | `-s` | `ref` | Sort field: `ref`, `branch`, `commit_id`, `author`, `committed_at`, `message`, `snapshot_id` |
| `--desc` | — | off | Reverse sort order (descending) |
| `--count` | — | `0` | Limit to first N refs after sorting (0 = unlimited) |
| `--no-commits` | — | off | Skip loading commit records; emit only `ref`, `branch`, `commit_id` |
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |

**Default output (text):** `<commit_id>  <ref>  <committed_at>  <author>` (or just `<commit_id>  <ref>` with `--no-commits`)

**`--json` output:**

```json
{
  "refs": [
    {
      "ref":          "refs/heads/dev",
      "branch":       "dev",
      "commit_id":    "sha256:<sha256>",
      "author":       "gabriel",
      "message":      "Add verse melody",
      "committed_at": "2026-01-01T00:00:00+00:00",
      "snapshot_id":  "sha256:<sha256>"
    }
  ],
  "count": 1,
  "current_branch": "dev"
}
```

With `--no-commits`, `author` / `message` / `committed_at` / `snapshot_id` are omitted.

**Example — three most recently committed branches:**

```sh
muse for-each-ref --sort committed_at --desc --count 3
```

| Exit | Meaning |
|---|---|
| 0 | Refs emitted (list may be empty) |
| 1 | Unknown `--sort` field, or negative `--count` |
| 3 | I/O error reading refs or commit records |

---

<a id="name-rev"></a>
### `name-rev` — map commit IDs to branch-relative names

For each supplied commit ID, performs a single multi-source BFS from all branch
tips and reports the closest branch and hop distance.  Results are expressed as
`<branch>~N` — where N is the number of parent hops from the tip.  When N is 0
(the commit is the exact branch tip) the name is the bare branch name with no
`~0` suffix.

```sh
muse name-rev <commit-id>... [-j] [--name-only] [-u <string>] [--stdin] [--branches GLOB] [--max-walk N]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--name-only` | — | off | Emit only the name (or the undefined string), not the commit ID |
| `--undefined` | `-u` | `"undefined"` | String to emit for unreachable commits |
| `--stdin` | — | off | Read additional commit IDs from stdin, one per line |
| `--branches` | — | — | Restrict BFS seeds to branch names matching this fnmatch glob |
| `--max-walk` | — | 50 000 | Maximum BFS steps before stopping |
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |

**Default output (text):** `<sha256>  main~3` (or `main~3` with `--name-only`)

**`--json` output:**

```json
{
  "results": [
    {
      "commit_id": "sha256:<sha256>",
      "input":     "<sha256>",
      "name":      "main~3",
      "branch":    "main",
      "distance":  3,
      "undefined": false,
      "ambiguous": false
    },
    {
      "commit_id": null,
      "input":     "deadbeef",
      "name":      null,
      "branch":    null,
      "distance":  null,
      "undefined": true,
      "ambiguous": false
    }
  ]
}
```

**Performance:** A single O(total-commits) BFS from all branch tips simultaneously.
Every commit is visited at most once regardless of how many input IDs are supplied.

| Exit | Meaning |
|---|---|
| 0 | All results computed (some may be `undefined` or `ambiguous`) |
| 1 | No commit IDs supplied, or non-hex input rejected |
| 3 | I/O error reading commit records |

---

<a id="check-ref-format"></a>
### `check-ref-format` — validate branch and ref names

Tests one or more names against Muse's branch-naming rules — the same
validation used by `muse branch` and `muse update-ref`.  Use in
scripts to pre-validate names before attempting to create a branch.

```sh
muse check-ref-format <name>... [-q] [-j] [--stdin] [--rules] [--invalid-only]
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--stdin` | — | off | Read additional names from stdin, one per line |
| `--rules` | — | off | Emit the validation ruleset as JSON and exit |
| `--quiet` | `-q` | off | No output — exit 0 if all valid, exit 1 otherwise |
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |
| `--invalid-only` | — | off | Show only invalid names in results |

**Rules enforced:** 1–255 chars; no C0 control characters, space, or DEL; no
backslash; no Git-banned punctuation (`~ ^ : ? * [`); no leading/trailing dot;
no consecutive dots (`..`); no leading/trailing or consecutive slashes; no
single-dot path component; no component ending in `.lock`; no `@{` sequence;
not the bare string `@`.

**`--json` output:**

```json
{
  "results": [
    {"name": "feat/my-branch", "valid": true,  "error": null},
    {"name": "bad..name",      "valid": false, "error": "..."}
  ],
  "all_valid": false,
  "valid_count": 1,
  "invalid_count": 1
}
```

**Default output (text):**
```
ok    feat/my-branch
FAIL  bad..name  →  Branch name 'bad..name' contains forbidden characters
```

With `--rules`:

```json
{"max_length": 255, "forbidden_chars": [...], "forbidden_patterns": [...], "notes": "..."}
```

**Shell conditional:**

```sh
muse check-ref-format -q "$BRANCH" && muse checkout -b "$BRANCH"
```

| Exit | Meaning |
|---|---|
| 0 | All names are valid, or `--rules` was used |
| 1 | One or more names are invalid; no names supplied; `--invalid-only` combined with `--quiet` or `--rules` |

(No exit 3 — this command is pure CPU, no I/O.)

---

<a id="verify-pack"></a>
### `verify-pack` — verify MPack integrity

Reads an MPack from stdin or `--file` and performs three-tier integrity
checking:

1. **Blob integrity** — every blob payload's SHA-256 is recomputed from the
   raw bytes.  The digest must match the declared `object_id`.
2. **Snapshot consistency** — every snapshot's manifest entries reference objects
   present in the bundle or already in the local store.
3. **Commit consistency** — every commit's `snapshot_id` is present in the bundle
   or already in the local store.

```sh
muse pack-objects main | muse verify-pack
muse verify-pack --file bundle.muse
```

| Flag | Short | Default | Description |
|---|---|---|---|
| `--file` | `-i` | `""` | Path to bundle file (reads stdin when omitted) |
| `--stat` | — | off | Fast structural inspection — counts only, no hashing |
| `--quiet` | `-q` | off | No output — exit 0 if clean, exit 1 on any failure |
| `--no-local` | `-L` | off | Skip local store checks (verify bundle in isolation) |
| `--strict` | — | off | Treat promised objects (absent locally but covered by a promisor remote) as integrity failures |
| `--json` | `-j` | off | Emit machine-readable JSON (default: human-readable text) |

**Default output (text):**

```
blobs=42  snapshots=5  commits=5  all_ok=True
```

**`--json` output:**

```json
{
  "blobs_checked":     42,
  "snapshots_checked": 5,
  "commits_checked":   5,
  "all_ok":            true,
  "failures":          [],
  "promised_objects":  0,
  "base_objects":      0,
  "bundle_mode":       "full",
  "base_commits":      []
}
```

**With failures:**

```json
{
  "all_ok": false,
  "failures": [
    {"kind": "object",   "id": "sha256:<sha256>", "error": "hash mismatch"},
    {"kind": "snapshot", "id": "sha256:<sha256>", "error": "missing object: ..."}
  ]
}
```

Objects absent from the mpack are resolved against the local store using a
three-state model: **PRESENT** (verified, not a failure), **PROMISED** (absent
locally but a promisor remote is configured — counted separately, not a
failure unless `--strict`), **MISSING** (absent with no promisor — always a
failure).

**Validate before upload:**

```sh
muse pack-objects main | muse verify-pack -q \
  && echo "mpack is clean — safe to push"
```

| Exit | Meaning |
|---|---|
| 0 | MPack is fully intact (or `--stat` completed) |
| 1 | One or more integrity failures; malformed msgpack; bad args |
| 3 | I/O error reading stdin or the mpack file |

---

---

## Composability Patterns — Advanced

### Name every commit reachable from a branch

```sh
# Get all commit IDs on feat/x since it diverged from dev
BASE=$(muse merge-base feat/x dev)
muse commit-graph --tip feat/x --stop-at "$BASE" \
  | xargs muse name-rev --name-only
```

### Audit all refs with full metadata and filter by recency

```sh
# List all branches modified in 2026, sorted newest-first
muse for-each-ref --sort committed_at --desc --json \
  | jq '.refs[] | select(.committed_at | startswith("2026"))'
```

### Validate a branch name before creating it

```sh
BRANCH="feat/my-feature"
muse check-ref-format -q "$BRANCH" \
  && echo "Name is valid — safe to branch" \
  || echo "Invalid branch name"
```

### Verify a bundle before shipping

```sh
muse pack-objects main | tee bundle.muse | muse verify-pack -q \
  && echo "bundle is clean — safe to push" \
  || echo "bundle has integrity failures — do not push"
```

### Switch active branch via plumbing

```sh
# Check where HEAD is now
muse symbolic-ref HEAD        # → refs/heads/main
# Redirect HEAD to dev
muse symbolic-ref HEAD --set dev
muse rev-parse HEAD           # → tip of dev
```

### Find stale branches (no commits in the last 30 days)

```sh
# Requires `date` and `jq`
CUTOFF=$(date -u -v-30d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
         || date -u --date="30 days ago" +%Y-%m-%dT%H:%M:%SZ)
muse for-each-ref --json \
  | jq --arg c "$CUTOFF" '.refs[] | select(.committed_at < $c) | .branch'
```

### Check which files changed between two branches

```sh
BASE=$(muse merge-base main feat/x)
muse snapshot-diff "$BASE" feat/x --stat
```

---

## Object ID Quick Reference

All IDs in Muse are canonical `sha256:<64-char lowercase hex>` digests. There are
three kinds:

| Kind | Computed from | Used by |
|---|---|---|
| **Object ID** | File bytes | `hash-object`, `cat-object`, snapshot manifests |
| **Snapshot ID** | Sorted `path:object_id` pairs | `read-snapshot`, `commit-tree` |
| **Commit ID** | Parent IDs + snapshot ID + message + timestamp | `read-commit`, `rev-parse`, `update-ref` |

Every ID is deterministic and content-addressed.  The same input always
produces the same ID; two different inputs never produce the same ID in
practice.

---

## Exit Code Summary

| Code | Constant | Meaning |
|---|---|---|
| 0 | `SUCCESS` | Command completed successfully |
| 1 | `USER_ERROR` | Bad input, ref not found, invalid format |
| 3 | `INTERNAL_ERROR` | I/O failure, integrity check, transport error |