# CLI Audit — Non-MIDI Commands

For every command listed below, ensure **all eight** of the following are in place:

1. **Comprehensive, idiomatic `run()` docstring** — uniform structure:
   - One-line summary sentence
   - Brief prose description (2–4 lines)
   - `Agent quickstart` block with `::` code fence showing 2–4 `--json` invocations
   - `JSON fields` section — one line per key, name left-padded, description after gap
   - `Exit codes` section — one line per code (`0  Success.`, `1  User error.`, etc.)

2. **Terse quickstart entry in `docs/agent-guide.md`** — one or two lines under the
   appropriate section heading.

3. **Envelope on every `--json` output** — `{**make_envelope(elapsed), ...}` pattern,
   `elapsed = start_timer()` at the top of `run()`.

4. **TypedDict inherits `EnvelopeJson`** — every JSON output shape uses the idiomatic wire type.

5. **`--json / -j` normalized** — `action="store_true"`, `dest="json_out"`, local var
   `json_out: bool = args.json_out`. No `--format/-f` dual-flag pattern. No `store_const`.

6. **Short flags idiomatic** — every flag that warrants a shorthand has one; no shorthand
   collides with convention (e.g. `-n` must not be used for `--name` when `-n` is the
   ecosystem-wide shorthand for `--dry-run`).

7. **Default output is text** — when `--json` is not passed, the command prints
   human-readable text (not JSON).  `json_out = False` → text path required.

8. **Flag tests complete** — test file has `TestRegisterFlags` covering every registered
   flag (`test_default_json_out_is_false`, `test_json_flag_sets_json_out`,
   `test_j_shorthand_sets_json_out`, plus one test per non-trivial flag).

---

## Status legend

- `[ ]` not started / not confirmed
- `[x]` confirmed done
- `[-]` not applicable

Columns: `d` docstring · `g` agent-guide · `e` envelope · `t` TypedDict ·
`j` --json/-j normalized · `dt` default text · `sf` short flags idiomatic · `ft` flag tests complete

---

## Cross-command flag conventions

Short flags that must be consistent across all commands that expose that concept:

| Flag | Short | Notes |
|------|-------|-------|
| `--json` | `-j` | All commands with JSON output |
| `--verbose` | `-v` | All commands with verbose mode |
| `--quiet` | `-q` | All commands with quiet mode |
| `--dry-run` | `-n` | All commands with dry-run mode |
| `--force` | `-f` | All commands with force mode |
| `--all` | `-a` | All commands with an "all" flag |
| `--branch` | `-b` | All commands accepting a branch name |
| `--message` | `-m` | All commands accepting a commit/shelf message |
| `--commit` | `-c` | All commands accepting a commit ref |
| `--file` | `-F` | All commands accepting a file path input |
| `--output` | `-o` | All commands writing to an output path |
| `--delete` | `-d` | All commands deleting something |
| `--recursive` | `-r` | All commands with recursive behavior |
| `--yes` | `-y` | All commands requiring confirmation bypass |
| `--name` | (none) | No short — avoid collision with `-n` (dry-run) |
| `--format` | (removed) | Replaced by `--json / -j` everywhere |

---

## Commands (alphabetical, MIDI excluded)

| Command | File | d | g | e | t | j | dt | sf | ft |
|---------|------|---|---|---|---|---|----|----|-----|
| age | cli/commands/age.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| agent keygen / list / register | cli/commands/agent.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| agent-config init/sync/read/status/inspect/set | cli/commands/agent_config.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| annotate | cli/commands/annotate.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| api-surface | cli/commands/api_surface.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| apply | cli/commands/apply.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| apply-patch | cli/commands/apply_patch.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| archive | cli/commands/archive.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| attributes | cli/commands/attributes.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| auth keygen/register/whoami/logout | cli/commands/auth.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| bisect | cli/commands/bisect.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| blame | cli/commands/blame.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| blast-risk | cli/commands/blast_risk.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| branch | cli/commands/branch.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| breakage | cli/commands/breakage.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| bundle create/inspect/verify/diff/unbundle | cli/commands/bundle.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| cat | cli/commands/cat.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| cat-object | cli/commands/cat_object.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| check | cli/commands/check.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| check-attr | cli/commands/check_attr.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| check-ignore | cli/commands/check_ignore.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| check-ref-format | cli/commands/check_ref_format.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| checkout | cli/commands/checkout.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| checkout-symbol | cli/commands/checkout_symbol.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| cherry-pick | cli/commands/cherry_pick.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| clean | cli/commands/clean.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| clone | cli/commands/clone.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| clones | cli/commands/clones.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| code-check | cli/commands/code_check.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| code-query | cli/commands/code_query.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| code-stage | cli/commands/code_stage.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| codemap | cli/commands/codemap.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| commit | cli/commands/commit.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| commit-graph | cli/commands/commit_graph.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| commit-tree | cli/commands/commit_tree.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| compare | cli/commands/compare.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| config | cli/commands/config_cmd.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| conflicts | cli/commands/conflicts.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| content-grep | cli/commands/content_grep.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| contract | cli/commands/contract.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| coord-gc | cli/commands/coord_gc.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| coord-sync | cli/commands/coord_sync.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| core-blame | cli/commands/core_blame.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| core-cat | cli/commands/core_cat.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| count-objects | cli/commands/count_objects.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| coupling | cli/commands/coupling.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| coverage | cli/commands/coverage.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| dag | cli/commands/dag.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| dead | cli/commands/dead.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| deps | cli/commands/deps.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| describe | cli/commands/describe.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| detect-refactor | cli/commands/detect_refactor.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| diff | cli/commands/diff.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| docs | cli/commands/docs_cmd.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| domain-info | cli/commands/domain_info.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| domains | cli/commands/domains.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| entangle | cli/commands/entangle.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| fetch | cli/commands/fetch.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| find-symbol | cli/commands/find_symbol.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| for-each-ref | cli/commands/for_each_ref.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| forecast | cli/commands/forecast.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| format-patch | cli/commands/format_patch.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| gc | cli/commands/gc.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| gravity | cli/commands/gravity.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| grep | cli/commands/grep.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| harmony | cli/commands/harmony.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| hash-object | cli/commands/hash_object.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| heartbeat-coord | cli/commands/heartbeat_coord.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| hotspots | cli/commands/hotspots.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| impact | cli/commands/impact.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| index-rebuild | cli/commands/index_rebuild.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| init | cli/commands/init.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| invariants | cli/commands/invariants.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| languages | cli/commands/languages.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| lineage | cli/commands/lineage.py | [x] | [x] | [x] | [x] | [x] | [x] | [x] | [x] |
| list-coord | cli/commands/list_coord.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| log | cli/commands/log.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| ls-files | cli/commands/ls_files.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| ls-remote | cli/commands/ls_remote.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| ls-tree | cli/commands/ls_tree.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| maintenance | cli/commands/maintenance.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| merge | cli/commands/merge.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| merge-base | cli/commands/merge_base.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| merge-tree | cli/commands/merge_tree.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| migrate | cli/commands/migrate.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| mv | cli/commands/mv.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| name-rev | cli/commands/name_rev.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| narrative | cli/commands/narrative.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| pack-objects | cli/commands/pack_objects.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| patch | cli/commands/patch.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| patch-id | cli/commands/patch_id.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| plan-merge | cli/commands/plan_merge.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| predict | cli/commands/predict.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| prune | cli/commands/prune.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| pull | cli/commands/pull.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| push | cli/commands/push.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| query | cli/commands/query.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| query-history | cli/commands/query_history.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| range-diff | cli/commands/range_diff.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| read | cli/commands/read.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| read-commit | cli/commands/read_commit.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| read-snapshot | cli/commands/read_snapshot.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| rebase | cli/commands/rebase.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| reconcile | cli/commands/reconcile.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| reflog | cli/commands/reflog.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [x] |
| release | cli/commands/release.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| release-coord | cli/commands/release_coord.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| remote | cli/commands/remote.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| rename | cli/commands/rename.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| reserve | cli/commands/reserve.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| reset | cli/commands/reset.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| restore | cli/commands/restore.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| rev-list | cli/commands/rev_list.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| rev-parse | cli/commands/rev_parse.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| revert | cli/commands/revert.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| rm | cli/commands/rm.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| semantic-cherry-pick | cli/commands/semantic_cherry_pick.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| semantic-test-coverage | cli/commands/semantic_test_coverage.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| shard | cli/commands/shard.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| shelf | cli/commands/shelf.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [x] |
| shortlog | cli/commands/shortlog.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| show-ref | cli/commands/show_ref.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| sign | cli/commands/sign.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| snapshot | cli/commands/snapshot_cmd.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| snapshot-diff | cli/commands/snapshot_diff.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| sparse-checkout | cli/commands/sparse_checkout.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| stable | cli/commands/stable.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| status | cli/commands/status.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| switch | cli/commands/switch.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [x] |
| symbol-log | cli/commands/symbol_log.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| symbolic-ref | cli/commands/symbolic_ref.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| symbols | cli/commands/symbols.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| tag | cli/commands/tag.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| task-queue | cli/commands/task_queue.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| test | cli/commands/test_cmd.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| trust | cli/commands/trust.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| type | cli/commands/type_cmd.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| unpack-objects | cli/commands/unpack_objects.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| update-ref | cli/commands/update_ref.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| velocity | cli/commands/velocity.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| verify | cli/commands/verify.py | [x] | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] |
| verify-commit | cli/commands/verify_commit.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| verify-object | cli/commands/verify_object.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| verify-pack | cli/commands/verify_pack.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| verify-tag | cli/commands/verify_tag.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| watch-coord | cli/commands/watch_coord.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| workspace | cli/commands/workspace.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |
| worktree | cli/commands/worktree.py | [x] | [x] | [x] | [x] | [ ] | [ ] | [ ] | [ ] |

---

## MIDI commands (excluded from this sprint)

agent_map, arpeggiate, cadence, contour, density, find_phrase, humanize,
instrumentation, intent, invert, midi_check, midi_compare, midi_harmony,
midi_query, midi_shard, mist, mix, motif_detect, note_blame, note_hotspots,
note_log, notes, piano_roll, quantize, retrograde, rhythm, scale_detect,
tempo, tension, transpose, velocity_normalize, velocity_profile, voice_leading