docs/reference/porcelain.md · gabriel/muse

1

# Muse Porcelain Commands

2

3

> **Layer guide:** Muse commands are organised into three tiers.

4

> This document covers **Tier 2 — Core Porcelain**: the high-level,

5

> human-friendly commands that build on the Tier 1 plumbing layer.

6

> Tier 3 commands (MIDI, Bitcoin, Code) live in their own reference docs.

7

8

All porcelain commands accept `--format json` where documented below. JSON is

9

printed to `stdout`; human text goes to `stdout` too; error messages always go

10

to `stderr`. Exit codes follow the same convention as the plumbing layer:

11

`0` success · `1` user error · `3` internal error.

---

## Quick Index

| Command | Description |

18

|---------|-------------|

19

| [`init`](#init) | Initialise a new Muse repository |

20

| [`commit`](#commit) | Record the working tree as a new version |

21

| [`status`](#status) | Show working-tree drift against HEAD |

22

| [`log`](#log) | Display commit history |

23

| [`diff`](#diff) | Compare working tree or two commits |

24

| [`show`](#show) | Inspect a commit — metadata, diff, files |

25

| [`branch`](#branch) | List, create, or delete branches |

26

| [`checkout`](#checkout) | Switch branches or restore a snapshot |

27

| [`merge`](#merge) | Three-way merge a branch into the current branch |

28

| [`rebase`](#rebase) | Replay commits onto a new base |

29

| [`reset`](#reset) | Move HEAD to a prior commit |

30

| [`revert`](#revert) | Undo a commit by creating a new one |

31

| [`cherry-pick`](#cherry-pick) | Apply a single commit's changes |

32

| [`stash`](#stash) | Shelve and restore uncommitted changes |

33

| [`tag`](#tag) | Attach and query semantic tags on commits |

34

| [`blame`](#blame) | Line-level attribution for any text file |

35

| [`reflog`](#reflog) | History of HEAD and branch-ref movements |

36

| [`rerere`](#rerere) | Reuse recorded conflict resolutions |

37

| [`gc`](#gc) | Garbage-collect unreachable objects |

38

| [`archive`](#archive) | Export a snapshot as tar.gz or zip |

39

| [`bisect`](#bisect) | Binary-search through history for a regression |

40

| [`worktree`](#worktree) | Multiple simultaneous branch checkouts |

41

| [`clean`](#clean) | Remove untracked files from the working tree |

42

| [`describe`](#describe) | Label a commit by its nearest tag |

43

| [`shortlog`](#shortlog) | Commit summary grouped by author or agent |

44

| [`verify`](#verify) | Whole-repository integrity check |

45

| [`snapshot`](#snapshot) | Explicit snapshot management |

46

| [`bundle`](#bundle) | Pack and unpack commits for offline transfer |

47

| [`content-grep`](#content-grep) | Full-text search across tracked file content |

48

| [`whoami`](#whoami) | Show the current identity |

49

| [`config`](#config) | Read and write repository configuration |

---

## Established Core Porcelain

54

55

56

### `init` — initialise a repository

57

58

Create a fresh `.muse/` directory in the current folder.

59

60

```

61

muse init # initialise in current dir

62

muse init --domain midi # set the active domain

63

muse init -d code # short flag

```

**Flags**

|------|-------|---------|-------------|

70

71

72

**Exit codes:** `0` success · `1` already initialised

---

### `commit` — record the working tree

78

79

Snapshot the working tree and write a commit pointing to it.

80

81

```

82

muse commit -m "verse melody"

83

muse commit --message "Add chorus" --author "gabriel"

84

muse commit --allow-empty

85

muse commit --format json

```

**Flags**

|------|-------|---------|-------------|

92

| `--message` | `-m` | `""` | Commit message |

93

94

| `--allow-empty` | `-e` | off | Commit even when nothing changed |

**JSON output**

```json

{

"commit_id": "a3f2...c8d1",

102

"branch": "main",

103

"message": "Add verse melody",

104

"author": "gabriel",

105

"committed_at": "2026-03-21T12:00:00+00:00",

106

"snapshot_id": "b7e4...f912",

107

"sem_ver_bump": "minor"

}

```

`sem_ver_bump` is `"none"`, `"patch"`, `"minor"`, or `"major"` depending on the

112

domain plugin's assessment of the change.

113

114

**Exit codes:** `0` committed · `1` nothing to commit (and `--allow-empty` not given)

---

### `status` — show drift against HEAD

```

muse status

muse status --short

muse status --json # machine-readable

muse status -s -j

```

**Flags**

|------|-------|---------|-------------|

132

| `--short` | `-s` | off | Compact one-line-per-file output |

133

| `--json` | `-j` | off | JSON output (equivalent to `--format json`) |

**Text output:**

```

On branch main

Modified:

tracks/bass.mid

Added:

tracks/lead.mid

```

`clean` when working tree matches HEAD.

**JSON output**

```json

{

"branch": "main",

"clean": false,

"modified": ["tracks/bass.mid"],

155

"added": ["tracks/lead.mid"],

"deleted": []

}

```

**Exit codes:** `0` always (non-zero drift is shown, not signalled)

---

### `log` — display commit history

```

muse log

muse log --limit 20

muse log --branch feat/audio

171

muse log --format json

```

**Flags**

|------|-------|---------|-------------|

178

179

| `--limit` | `-n` | 50 | Max commits to emit |

180

181

182

**JSON output** — an array of commit records, newest first:

```json

[

{

"commit_id": "a3f2...c8d1",

188

"branch": "main",

189

"message": "Add verse melody",

190

"author": "gabriel",

191

"committed_at": "2026-03-21T12:00:00+00:00",

192

"snapshot_id": "b7e4...f912",

193

"parent_commit_id": "ff01...23ab",

194

"sem_ver_bump": "minor"

}

]

```

**Exit codes:** `0` always

---

### `diff` — compare working tree or two commits

205

206

```

207

muse diff # working tree vs HEAD

208

muse diff --from HEAD~3

209

muse diff --from v1.0 --to v2.0

210

muse diff --format json

```

**Flags**

|------|-------|---------|-------------|

217

218

| `--to` | `-t` | working tree | Ref or commit to diff to |

**JSON output**

```json

{

"from": "ff01...23ab",

226

"to": "a3f2...c8d1",

227

"added": ["tracks/lead.mid"],

228

"removed": ["tracks/old.mid"],

229

"modified": ["tracks/bass.mid"],

"total_changes": 3

}

```

> **Note:** The JSON field is `"total_changes"` (not `"ops"` or `"changes"`).

235

236

**Exit codes:** `0` always

---

### `show` — inspect a commit

```

muse show HEAD

muse show abc123

muse show --format json

247

muse show --stat HEAD # files changed, not full diff

```

**Flags**

|------|-------|---------|-------------|

254

| `--ref` | `-r` | HEAD | Commit or branch to inspect |

255

| `--stat` | `-s` | off | Show file-level summary instead of raw diff |

256

257

258

**JSON output — full diff mode**

```json

{

"commit_id": "a3f2...c8d1",

263

"branch": "main",

264

"message": "Add verse melody",

265

"author": "gabriel",

266

"committed_at": "2026-03-21T12:00:00+00:00",

267

"snapshot_id": "b7e4...f912",

268

"parent_commit_id": "ff01...23ab",

269

"delta": {

270

"added": ["tracks/lead.mid"],

271

"removed": [],

272

"modified": ["tracks/bass.mid"]

}

}

```

**JSON output — `--stat` mode**

```json

{

"commit_id": "a3f2...c8d1",

282

"branch": "main",

283

"message": "Add verse melody",

284

"author": "gabriel",

285

"committed_at": "2026-03-21T12:00:00+00:00",

286

"snapshot_id": "b7e4...f912",

287

"parent_commit_id": "ff01...23ab",

"files_added": 1,

"files_removed": 0,

"files_modified": 1

}

```

**Exit codes:** `0` found · `1` commit not found

---

### `branch` — list, create, or delete branches

300

301

```

302

muse branch # list all

303

muse branch feat/reverb # create

304

muse branch --delete feat/reverb

305

muse branch -d feat/reverb # short flag

306

muse branch --format json # structured list

```

**Flags**

|------|-------|---------|-------------|

313

| `--delete` | `-d` | off | Delete a branch |

314

315

316

**JSON output — list**

```json

{

"current": "main",

"branches": [

{"name": "dev", "commit_id": "ff01...23ab", "is_current": false},

323

{"name": "main", "commit_id": "a3f2...c8d1", "is_current": true}

]

}

```

**JSON output — create / delete**

329

330

```json

331

{"action": "created", "branch": "feat/reverb"}

332

{"action": "deleted", "branch": "feat/reverb"}

333

```

334

335

**Exit codes:** `0` success · `1` branch already exists (create) or not found (delete)

---

### `checkout` — switch branches or restore snapshot

```

muse checkout main

muse checkout feat/guitar

345

muse checkout --create feat/new-idea # create and switch

346

muse checkout -c feat/new-idea # short flag

347

muse checkout --format json # machine-readable result

```

**Flags**

|------|-------|---------|-------------|

354

| `--create` | `-c` | off | Create branch then switch |

**JSON output**

```json

{

"action": "switched",

362

"branch": "feat/guitar",

363

"commit_id": "a3f2...c8d1"

}

```

`"action"` is one of `"switched"`, `"created"`, or `"already_on"` (when you

368

check out the branch that is already active).

369

370

**Exit codes:** `0` success · `1` branch not found (and `--create` not given)

---

### `merge` — three-way merge

376

377

```

378

muse merge feat/audio

379

muse merge --message "Merge audio feature"

380

muse merge --abort

381

muse merge --continue

382

muse merge --format json

```

**Flags**

|------|-------|---------|-------------|

389

390

| `--abort` | `-a` | off | Abort an in-progress merge |

391

| `--continue` | `-c` | off | Resume after resolving conflicts |

392

393

394

**JSON output — clean merge**

```json

{

"action": "merged",

"branch": "feat/audio",

400

"commit_id": "a3f2...c8d1",

401

"message": "Merge feat/audio into main"

}

```

**JSON output — conflict**

```json

{

"action": "conflict",

410

"branch": "feat/audio",

411

"conflicts": ["tracks/bass.mid"]

}

```

**Conflict flow:**

1. `muse merge <branch>` → conflict reported, writes `MERGE_STATE.json`

417

2. Resolve files manually

418

3. `muse merge --continue` → commit the merge

419

4. Or `muse merge --abort` → restore original HEAD

420

421

**Exit codes:** `0` merged · `1` conflict or bad arguments

---

### `rebase` — replay commits onto a new base

427

428

Muse rebase replays a sequence of commits onto a new base using the same

429

three-way merge engine as `muse merge`. Because commits are content-addressed,

430

each replayed commit gets a **new ID** — the originals are untouched in the store.

431

432

```

433

muse rebase main # replay current branch onto main

434

muse rebase --onto newbase upstream # replay onto a specific base

435

muse rebase --squash main # collapse all commits into one

436

muse rebase --squash -m "feat: all in" # squash with custom message

437

muse rebase --abort # restore original HEAD

438

muse rebase --continue # resume after conflict resolution

439

muse rebase --format json

```

**Flags**

| Flag | Short | Description |

445

|------|-------|-------------|

446

| `--onto <ref>` | `-o` | New base commit |

447

| `--squash` | `-s` | Collapse all commits into one |

448

| `--message <msg>` | `-m` | Message for squash commit |

449

| `--abort` | `-a` | Abort and restore original HEAD |

450

| `--continue` | `-c` | Resume after resolving a conflict |

451

| `--format <fmt>` | `-f` | `text` or `json` |

452

453

**JSON output — squash rebase**

```json

{

"action": "squash_rebase",

458

"onto": "main",

459

"new_commit_id": "a3f2...c8d1",

460

"commits_squashed": 4,

461

"branch": "feat/audio"

}

```

**JSON output — normal rebase**

```json

{

"action": "rebase",

"onto": "main",

"branch": "feat/audio",

472

"commits_replayed": 4,

473

"new_tip": "a3f2...c8d1"

}

```

**Conflict flow:**

1. `muse rebase main` → conflict reported, writes `REBASE_STATE.json` and `MERGE_STATE.json`

479

2. Resolve files manually

480

3. `muse rebase --continue` → commit the resolved state and continue

481

4. Or `muse rebase --abort` → restore the original branch pointer

482

483

**State file:** `.muse/REBASE_STATE.json` — tracks remaining/completed commits

484

and the `onto` base. Cleared automatically on successful completion or `--abort`.

485

486

**Exit codes:** `0` clean · `1` conflict or bad arguments

---

### `reset` — move HEAD to a prior commit

492

493

```

494

muse reset HEAD~1 # move back one commit

495

muse reset abc123 # move to specific commit

496

muse reset --hard # also reset working tree

497

muse reset --format json

```

**Flags**

|------|-------|---------|-------------|

504

| `--hard` | `-H` | off | Also update the working tree to match |

**JSON output**

```json

{

"action": "reset",

"branch": "main",

"previous_commit": "a3f2...c8d1",

514

"new_commit": "ff01...23ab",

"hard": false

}

```

**Exit codes:** `0` success · `1` commit not found

---

### `revert` — undo a commit by creating a new one

525

526

Non-destructive: the original commit remains in history. A new commit is

527

created whose effect is the inverse of the target commit.

```

muse revert HEAD

muse revert abc123

muse revert --message "Undo broken change"

533

muse revert --format json

```

**Flags**

|------|-------|---------|-------------|

**JSON output**

```json

{

"action": "reverted",

548

"reverted_commit": "a3f2...c8d1",

549

"new_commit_id": "b7e4...f912",

550

"branch": "main",

551

"message": "Revert \"Add verse melody\""

}

```

**Exit codes:** `0` success · `1` commit not found or nothing to revert

---

### `cherry-pick` — apply a single commit's changes

561

562

```

563

muse cherry-pick abc123

564

muse cherry-pick abc123 --message "Cherry: verse fix"

565

muse cherry-pick abc123 --format json

```

**Flags**

|------|-------|---------|-------------|

**JSON output**

```json

{

"action": "cherry_picked",

580

"source_commit": "abc1...2345",

581

"new_commit_id": "a3f2...c8d1",

582

"branch": "main",

583

"message": "Cherry: verse fix"

}

```

**Exit codes:** `0` success · `1` commit not found or conflict

---

### `stash` — shelve and restore changes

593

594

```

595

muse stash push -m "WIP: bridge section"

596

muse stash list

597

muse stash list --format json

muse stash pop

muse stash drop 0

```

**Subcommands**

| Subcommand | Description |

605

|------------|-------------|

606

| `push` | Stash current working-tree changes |

607

| `list` | List saved stashes |

608

| `pop` | Restore the most recent stash and drop it |

609

| `apply <n>` | Restore stash N without dropping it |

610

| `drop <n>` | Delete stash N |

611

| `show <n>` | Show what a stash contains |

**Flags — `push`**

| Flag | Short | Description |

616

|------|-------|-------------|

617

| `--message` | `-m` | Label for the stash entry |

618

619

**Flags — `list` / `show`**

620

621

| Flag | Short | Description |

622

|------|-------|-------------|

623

| `--format` | `-f` | `text` or `json` |

624

625

**JSON output — `list`**

```json

[

{

"index": 0,

"message": "WIP: bridge section",

632

"created_at": "2026-03-21T12:00:00+00:00",

633

"branch": "feat/audio"

}

]

```

**Exit codes:** `0` success · `1` stash index out of range or nothing to stash

---

### `tag` — semantic tags on commits

```

muse tag v1.0.0

muse tag v1.0.0 --commit abc123

648

muse tag list

649

muse tag list --format json

650

muse tag delete v0.9.0

651

muse tag show v1.0.0 --format json

```

**Subcommands**

| Subcommand | Description |

657

|------------|-------------|

658

| `<name>` | Create a tag on HEAD (or `--commit`) |

659

| `list` | List all tags |

660

| `show <name>` | Inspect a tag |

661

| `delete <name>` | Delete a tag |

**Flags — create**

| Flag | Short | Description |

666

|------|-------|-------------|

667

| `--commit` | `-c` | Attach tag to a specific commit ID |

668

| `--message` | `-m` | Optional annotation |

669

| `--format` | `-f` | `text` or `json` |

670

671

**JSON output — create**

672

673

```json

674

{"action": "created", "name": "v1.0.0", "commit_id": "a3f2...c8d1"}

675

```

676

677

**JSON output — `list`**

```json

[

{"name": "v1.0.0", "commit_id": "a3f2...c8d1", "created_at": "2026-03-21T12:00:00+00:00"}

]

```

**Exit codes:** `0` success · `1` tag or commit not found

---

### `blame` — line-level attribution

```

muse blame song.mid

muse blame --format json song.mid

```

**Flags**

|------|-------|---------|-------------|

701

702

| `--ref` | `-r` | HEAD | Branch or commit to blame against |

**JSON output**

```json

[

{

"line": 1,

"content": "tempo: 120",

711

"commit_id": "a3f2...c8d1",

712

"author": "gabriel",

713

"committed_at": "2026-03-21T12:00:00+00:00",

714

"message": "Add verse melody"

}

]

```

**Exit codes:** `0` success · `1` file or ref not found

---

### `reflog` — HEAD and branch movement history

```

muse reflog

muse reflog --branch feat/audio

729

muse reflog --limit 50

730

muse reflog --format json

```

**Flags**

|------|-------|---------|-------------|

737

738

| `--limit` | `-n` | 50 | Max entries to show |

739

740

741

The reflog is the "undo safety net" — every ref movement is recorded so

742

you can recover from accidental resets, force-pushes, or botched rebases.

**JSON output**

```json

[

{

"index": 0,

"commit_id": "a3f2...c8d1",

751

"action": "commit",

752

"message": "Add verse melody",

753

"author": "gabriel",

754

"moved_at": "2026-03-21T12:00:00+00:00"

}

]

```

`"index"` is 0-based, with 0 being the most recent entry. `"action"` describes

760

what caused the ref movement: `"commit"`, `"merge"`, `"rebase"`, `"reset"`, `"checkout"`, etc.

761

762

**Exit codes:** `0` always

---

### `rerere` — reuse recorded resolutions

768

769

```

770

muse rerere list # show cached resolutions

771

muse rerere apply # auto-apply cached fixes to current conflicts

772

muse rerere forget abc123 # remove a cached resolution

773

muse rerere status # show which conflicts have cached resolutions

774

```

775

776

**How it works:** After a successful merge, Muse records the resolution in

777

`.muse/rerere/`. On future conflicts with the same "conflict fingerprint",

778

`rerere apply` replays the resolution automatically.

779

780

**Exit codes:** `0` resolution applied or listed · `1` no matching resolution

---

### `gc` — garbage collect

786

787

Removes objects that are not reachable from any branch or tag ref. Orphaned

788

commits (e.g. after a reset), dangling snapshots, and unreferenced blobs are

all eligible.

```

muse gc # remove unreachable objects

793

muse gc --dry-run # preview what would be removed

794

muse gc -n # short flag for --dry-run

795

muse gc --format json

```

**Flags**

|------|-------|---------|-------------|

802

| `--dry-run` | `-n` | off | Preview without deleting |

**JSON output**

```json

{

"commits_removed": 2,

810

"snapshots_removed": 2,

811

"objects_removed": 11,

812

"bytes_freed": 204800,

"dry_run": false

}

```

**Exit codes:** `0` always

---

### `archive` — export a snapshot

```

muse archive HEAD

muse archive HEAD --format zip --output release.zip

827

muse archive v1.0.0 --prefix project/

```

**Flags**

|------|-------|---------|-------------|

834

835

836

| `--prefix` | `-p` | `""` | Directory prefix inside the archive |

837

838

All archive entries use the `prefix/` directory. Tar-slip / zip-slip are

839

prevented: entry paths are validated to stay within the prefix.

840

841

**Exit codes:** `0` archive written · `1` ref not found · `3` I/O error

---

### `bisect` — binary-search for a regression

847

848

Muse bisect works on any domain — not just code. Use it to find which commit

849

introduced a melody change, a tuning drift, or a data regression.

```

muse bisect start

muse bisect bad HEAD # mark HEAD as bad (broken)

854

muse bisect good v1.0.0 # mark v1.0.0 as good (working)

855

muse bisect bad # mark the currently-tested commit as bad

856

muse bisect good # mark the currently-tested commit as good

857

muse bisect skip # skip an untestable commit

858

muse bisect log # show the current session log

859

muse bisect reset # end the session and restore HEAD

860

muse bisect run pytest # automated bisect: run command, 0=good, 1=bad

```

**Subcommands**

| Subcommand | Description |

866

|------------|-------------|

867

| `start` | Begin a new bisect session |

868

| `bad [<ref>]` | Mark a commit as bad; omit to mark current |

869

| `good [<ref>]` | Mark a commit as good; omit to mark current |

870

| `skip [<ref>]` | Skip a commit that cannot be tested |

871

| `log` | Print the current session state |

872

| `reset` | End the session; restore the original branch |

873

| `run <cmd>` | Automate: run command, exit 0 = good, exit 1 = bad |

874

875

Bisect narrows the search range using binary search. On each step, Muse

876

checks out the midpoint commit and waits for a verdict (`good`/`bad`/`skip`).

877

The search converges in O(log N) steps regardless of domain.

878

879

**Exit codes:** `0` session active or found · `1` bad arguments · `3` I/O error

---

### `worktree` — multiple simultaneous checkouts

885

886

```

887

muse worktree add /path/to/dir feat/audio

888

muse worktree list

889

muse worktree list --format json

890

muse worktree remove feat/audio

muse worktree prune

```

**Subcommands**

| Subcommand | Description |

897

|------------|-------------|

898

| `add <path> <branch>` | Check out `branch` into `path` |

899

| `list` | List registered worktrees |

900

| `remove <branch>` | Remove a linked worktree |

901

| `prune` | Remove entries for deleted directories |

**Flags — `list`**

| Flag | Short | Description |

906

|------|-------|-------------|

907

| `--format` | `-f` | `text` or `json` |

908

909

**JSON output — `list`**

```json

[

{"path": "/home/g/muse-main", "branch": "main", "is_main": true},

914

{"path": "/home/g/muse-audio", "branch": "feat/audio", "is_main": false}

]

```

**Exit codes:** `0` success · `1` path or branch conflict

---

### `clean` — remove untracked files

924

925

Scans the working tree against the HEAD snapshot and removes files not tracked

926

in any commit. `--force` is required to actually delete files (safety guard).

927

928

```

929

muse clean -n # dry-run: show what would be removed

930

muse clean -f # delete untracked files

931

muse clean -f -d # also delete empty directories

932

muse clean -f -x # also delete .museignore-excluded files

933

muse clean -f -d -x # everything untracked + ignored + empty dirs

```

**Flags**

| Flag | Short | Description |

939

|------|-------|-------------|

940

| `--dry-run` | `-n` | Preview without deleting |

941

| `--force` | `-f` | Required to actually delete |

942

| `--directories` | `-d` | Remove empty untracked directories |

943

| `--include-ignored` | `-x` | Also remove .museignore-excluded files |

944

945

**Exit codes:** `0` clean or cleaned · `1` untracked exist but `--force` not given

---

### `describe` — label by nearest tag

951

952

Walks backward from a commit and finds the nearest tag. Returns `<tag>~N`

953

where N is the hop count. N=0 gives the bare tag name.

954

955

```

956

muse describe # → v1.0.0~3

957

muse describe --ref feat/audio # describe the tip of a branch

958

muse describe --long # → v1.0.0-3-gabc123456789

959

muse describe --require-tag # exit 1 if no tags exist

960

muse describe --format json # machine-readable

```

**Flags**

| Flag | Short | Description |

966

|------|-------|-------------|

967

| `--ref <ref>` | `-r` | Branch or commit to describe |

968

| `--long` | `-l` | Always show `<tag>-<dist>-g<sha>` |

969

| `--require-tag` | `-t` | Fail if no tag found |

970

| `--format <fmt>` | `-f` | `text` or `json` |

971

972

**JSON output schema:**

```json

{

"commit_id": "string (full SHA-256)",

977

"tag": "string | null",

978

"distance": 0,

979

"short_sha": "string (12 chars)",

980

"name": "string (e.g. v1.0.0~3)"

}

```

**Exit codes:** `0` description produced · `1` ref not found or `--require-tag` with no tags

---

### `shortlog` — commit summary by author or agent

990

991

Groups commits by `author` or `agent_id` and prints a count + message list.

992

Especially expressive in Muse because both human and agent contributions are

993

tracked with full metadata.

994

995

```

996

muse shortlog # current branch

997

muse shortlog --all # all branches

998

muse shortlog --numbered # sort by commit count (most active first)

999

muse shortlog --email # include agent_id alongside author name

1000

muse shortlog --limit 100 # cap commit walk at 100

1001

muse shortlog --format json # JSON for agent consumption

```

**Flags**

| Flag | Short | Description |

1007

|------|-------|-------------|

1008

| `--branch <br>` | `-b` | Branch to summarise |

1009

| `--all` | `-a` | Summarise all branches |

1010

| `--numbered` | `-n` | Sort by commit count |

1011

| `--email` | `-e` | Include agent_id |

1012

| `--limit <N>` | `-l` | Max commits to walk |

1013

| `--format <fmt>` | `-f` | `text` or `json` |

1014

1015

**JSON output schema:**

```json

[

{

"author": "string",

"count": 12,

"commits": [

{"commit_id": "...", "message": "...", "committed_at": "..."}

]

}

]

```

**Exit codes:** `0` always

---

### `verify` — whole-repository integrity check

1035

1036

Walks every reachable commit from every branch ref and performs a three-tier check:

1037

1038

1. Every branch ref points to an existing commit.

1039

2. Every commit's snapshot exists.

1040

3. Every object referenced by every snapshot exists, and (unless `--no-objects`)

1041

its SHA-256 is recomputed to detect silent data corruption.

1042

1043

This is Muse's equivalent of `git fsck`.

1044

1045

```

1046

muse verify # full integrity check (re-hashes all objects)

1047

muse verify --no-objects # existence-only check (faster)

1048

muse verify --quiet # exit code only — no output

1049

muse verify -q && echo "healthy"

1050

muse verify --format json | jq '.failures'

```

**Flags**

| Flag | Short | Description |

1056

|------|-------|-------------|

1057

| `--quiet` | `-q` | No output; exit 0 = clean, 1 = failure |

1058

| `--no-objects` | `-O` | Skip SHA-256 re-hashing |

1059

| `--format <fmt>` | `-f` | `text` or `json` |

1060

1061

**JSON output schema:**

```json

{

"refs_checked": 3,

"commits_checked": 42,

1067

"snapshots_checked": 42,

1068

"objects_checked": 210,

"all_ok": true,

"failures": [

{

"kind": "object",

"id": "abc123...",

"error": "hash mismatch — data corruption detected"

}

]

}

```

**Failure kinds:** `ref` · `commit` · `snapshot` · `object`

1081

1082

**Exit codes:** `0` all checks passed · `1` one or more failures

---

### `snapshot` — explicit snapshot management

1088

1089

A snapshot is Muse's fundamental unit of state: an immutable, content-addressed

1090

record mapping workspace paths to their SHA-256 object IDs.

1091

1092

`muse snapshot` exposes snapshots as a first-class operation — capture, list,

1093

show, and export them independently of commits. Useful for mid-work checkpoints

1094

in agent pipelines.

1095

1096

#### `snapshot create`

```

muse snapshot create

muse snapshot create -m "WIP: before refactor"

1101

muse snapshot create --format json # prints snapshot_id

```

**JSON output:**

```json

{

"snapshot_id": "string",

1109

"file_count": 42,

1110

"note": "string",

1111

"created_at": "ISO8601"

}

```

#### `snapshot list`

```

muse snapshot list

muse snapshot list --limit 5

1120

muse snapshot list --format json

```

#### `snapshot show`

```

muse snapshot show <snapshot_id>

1127

muse snapshot show abc123 # prefix lookup

1128

muse snapshot show abc123 --format text

1129

```

1130

1131

#### `snapshot export`

1132

1133

```

1134

muse snapshot export <snapshot_id>

1135

muse snapshot export abc123 --format zip --output release.zip

1136

muse snapshot export abc123 --prefix project/

1137

```

1138

1139

**Archive formats:** `tar.gz` (default) · `zip`

**Flags (export):**

| Flag | Short | Description |

1144

|------|-------|-------------|

1145

| `--format <fmt>` | `-f` | `tar.gz` or `zip` |

1146

| `--output <path>` | `-o` | Output file path |

1147

| `--prefix <str>` | | Directory prefix inside archive |

1148

1149

**Exit codes:** `0` success · `1` snapshot not found

---

### `bundle` — offline commit transfer

1155

1156

A bundle is a self-contained JSON file carrying commits, snapshots, and objects.

1157

Copy it over SSH, USB, or email — no network connection required.

1158

1159

The bundle format is identical to the plumbing `PackBundle` JSON and is

human-inspectable.

#### `bundle create`

```

muse bundle create out.bundle # bundle from HEAD

1166

muse bundle create out.bundle feat/audio # bundle a specific branch

1167

muse bundle create out.bundle HEAD --have old-sha # delta bundle

1168

```

1169

1170

#### `bundle unbundle`

1171

1172

```

1173

muse bundle unbundle repo.bundle # apply and update branch refs

1174

muse bundle unbundle repo.bundle --no-update-refs # objects only

```

#### `bundle verify`

```

muse bundle verify repo.bundle

1181

muse bundle verify repo.bundle --quiet

1182

muse bundle verify repo.bundle --format json

1183

```

1184

1185

#### `bundle list-heads`

1186

1187

```

1188

muse bundle list-heads repo.bundle

1189

muse bundle list-heads repo.bundle --format json

1190

```

1191

1192

**Bundle value-add over plumbing:** `unbundle` updates local branch refs from

1193

the bundle's `branch_heads` map, so the receiver's repo reflects the sender's

1194

branch state automatically.

1195

1196

**Exit codes:** `0` success · `1` file not found, corrupt, or bad args

---

### `content-grep` — full-text search across tracked files

1202

1203

Searches every file in the HEAD snapshot for a pattern. Files are read from

1204

the content-addressed object store. Binary files and non-UTF-8 files are

1205

silently skipped.

1206

1207

Muse-specific: the search target is the **immutable object store** — you're

1208

searching a specific point in history, not the working tree.

1209

1210

```

1211

muse content-grep --pattern "Cm7"

1212

muse content-grep --pattern "TODO|FIXME" --files-only

1213

muse content-grep --pattern "verse" --ignore-case

1214

muse content-grep --pattern "tempo" --format json

1215

muse content-grep --pattern "chord" --ref feat/harmony

1216

muse content-grep --pattern "hit" --count

```

**Flags**

| Flag | Short | Description |

1222

|------|-------|-------------|

1223

| `--pattern <regex>` | `-p` | Python regex to search for |

1224

| `--ref <ref>` | `-r` | Branch or commit to search |

1225

| `--ignore-case` | `-i` | Case-insensitive matching |

1226

| `--files-only` | `-l` | Print only matching file paths |

1227

| `--count` | `-c` | Print match count per file |

1228

| `--format <fmt>` | `-f` | `text` or `json` |

1229

1230

**JSON output schema:**

```json

[

{

"path": "song.txt",

"object_id": "abc123...",

1237

"match_count": 3,

1238

"matches": [

1239

{"line_number": 4, "text": "chord: Cm7"}

]

}

]

```

**Exit codes:** `0` at least one match · `1` no matches

---

### `whoami` — show the current identity

1251

1252

A shortcut for `muse auth whoami`.

```

muse whoami

muse whoami --json # JSON output for agent consumers

1257

muse whoami --all # show identities for all configured hubs

```

**Flags**

| Flag | Short | Description |

1263

|------|-------|-------------|

1264

| `--json` | `-j` | JSON output |

1265

| `--all` | `-a` | Show all hub identities |

**Text output:**

```

hub: app.musehub.ai

type: agent

name: mozart-agent-v2

id: usr_abc123

token: set

```

**JSON output:**

```json

{

"hub": "app.musehub.ai",

1282

"type": "agent",

1283

"name": "mozart-agent-v2",

1284

"id": "usr_abc123",

1285

"token_set": true,

1286

"capabilities": ["push", "pull", "share"]

}

```

`"token_set"` is a boolean. `"capabilities"` lists the operations the current

1291

token is authorised for on the configured hub.

1292

1293

**Exit codes:** `0` identity found · `1` no identity stored (not authenticated)

---

## Domain Auth & Config

1298

1299

### `auth` — identity management

1300

1301

```

1302

muse auth login --hub app.musehub.ai

1303

muse auth login --agent --agent-id mozart-v2 --model gpt-4.5

muse auth whoami

muse auth logout

```

---

### `config` — repository configuration

1312

1313

Read and write repository configuration stored in `.muse/config.toml`.

1314

1315

```

1316

muse config show # full config as text

1317

muse config show --format json # machine-readable

1318

muse config get core.author # single value

1319

muse config set core.author "Gabriel" # write a value

```

**Subcommands**

| Subcommand | Description |

1325

|------------|-------------|

1326

| `show` | Print the entire config |

1327

| `get <key>` | Print a single key's value |

1328

| `set <key> <value>` | Write a key/value pair |

**Flags — `show`**

| Flag | Short | Description |

1333

|------|-------|-------------|

1334

| `--format` | `-f` | `text` or `json` |

1335

1336

**JSON output — `show`**

```json

{

"user": {

"author": "gabriel",

"email": ""

},

"hub": {

"url": "https://app.musehub.ai"

1346

},

1347

"remotes": {

1348

"origin": "https://app.musehub.ai/repos/my-repo"

},

"domain": {

"my.key": "value"

}

}

```

Top-level sections:

- `user` — local author identity

1358

- `hub` — MuseHub connection (HTTPS URLs only)

1359

- `remotes` — named remote URLs

1360

- `domain` — domain-specific key/value pairs (any `domain.*` key is permitted)

1361

1362

**Blocked namespaces:** `auth.*` and `remotes.*` keys cannot be written via

1363

`config set` — use dedicated commands (`muse auth login`, `muse remote add`).

1364

1365

**Exit codes:** `0` success · `1` key not found, blocked namespace, or bad format

---

### `hub` — MuseHub connection

1370

1371

```

1372

muse hub connect https://app.musehub.ai

muse hub status

muse hub disconnect

```

---

## Composability Patterns

1380

1381

Muse porcelain commands are designed to compose cleanly in pipelines.

1382

1383

**Check integrity before every push:**

1384

1385

```bash

1386

muse verify --quiet || { echo "repo corrupt!"; exit 1; }

muse push

```

**Offline collaboration via bundle:**

```bash

# Sender:

muse bundle create session.bundle

1395

scp session.bundle colleague:/tmp/

1396

1397

# Receiver:

1398

muse bundle verify /tmp/session.bundle --quiet

1399

muse bundle unbundle /tmp/session.bundle

1400

```

1401

1402

**Generate a release label in CI:**

1403

1404

```bash

1405

VERSION=$(muse describe --format json | jq -r .name)

1406

echo "Building $VERSION..."

1407

muse snapshot export HEAD --output "${VERSION}.tar.gz"

1408

```

1409

1410

**Find which commits touched a melody line:**

1411

1412

```bash

1413

muse content-grep --pattern "tempo: 120" --format json | jq '.[].path'

1414

```

1415

1416

**Agent activity summary:**

1417

1418

```bash

1419

muse shortlog --all --numbered --email --format json \

1420

| jq '.[] | select(.author | test("agent")) | {agent: .author, count: .count}'

1421

```

1422

1423

**Checkpoint before a risky refactor:**

1424

1425

```bash

1426

SNAP=$(muse snapshot create -m "pre-refactor" --format json | jq -r .snapshot_id)

1427

# ... do the work ...

1428

muse snapshot show "$SNAP" --format json | jq '.manifest | keys'

1429

```

1430

1431

**Binary-search for the broken commit (automated):**

```bash

muse bisect start

muse bisect bad HEAD

muse bisect good v1.0.0

1437

muse bisect run pytest tests/regression.py

1438

# Muse prints the first bad commit and resets automatically.

1439

```

1440

1441

**Audit all recent changes by agents:**

1442

1443

```bash

1444

muse log --format json | jq '[.[] | select(.author | startswith("agent-"))]'

1445

```