# CLI 참조

> 공개 `scripts/` 명령, subcommand, 주요 option, exit code 차이, 문서 표와 실제 실행 파일 surface를 검증하는 테스트를 정리합니다.

- Repository: local/master-ops-with-local-mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3
- Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt

## Source Files

- `local-mogui-ade-orchestrator:docs/public/reference.md`
- `local-mogui-ade-orchestrator:scripts/dispatch-gate`
- `local-mogui-ade-orchestrator:scripts/master-succeed`
- `local-mogui-ade-orchestrator:scripts/master-bootstrap-live`
- `local-mogui-ade-orchestrator:scripts/workspace-descriptor-check`
- `local-mogui-ade-orchestrator:tests/test_reference_command_table.py`

---

---
title: "CLI 참조"
description: "공개 `scripts/` 명령, subcommand, 주요 option, exit code 차이, 문서 표와 실제 실행 파일 surface를 검증하는 테스트를 정리합니다."
---

`local-mogui-ade-orchestrator`의 공개 CLI surface는 실행 가능한 `scripts/` 파일과 `docs/public/reference.md`의 명령 표로 관리된다. 표는 자동 생성물이 아니며, `tests/test_reference_command_table.py`가 각 실행 파일의 `--help` 출력에서 subcommand 집합을 측정해 문서 row와 비교한다. `local-master-ops`는 설치된 ops 레이어용 래퍼와 운영 가드를 별도로 노출하며, 일부 스크립트는 placeholder 치환 후 실제 ops 저장소에서 실행되는 형태다.

## 저장소별 실행 위치

| 저장소 | 용도 | 대표 실행 경로 |
| --- | --- | --- |
| `local-mogui-ade-orchestrator` | 런타임 코어, bootstrap, succession, dispatch gate, redaction, model audit | `local-mogui-ade-orchestrator:scripts/<command>` |
| `local-master-ops` | 설치된 ops 레이어, 작업자 dispatch 래퍼, Orca 대기/스윕, 템플릿 적용/검사, PR/대화면 가드 | `local-master-ops:scripts/<command>` |

<Warning>
두 저장소의 `scripts/`는 같은 역할이 아니다. `local-mogui-ade-orchestrator:scripts/dispatch-gate`는 gate 판정 엔진이고, `local-master-ops:scripts/dispatch`는 gate, Orca task 생성, terminal dispatch, register probe를 묶는 ops-side 래퍼다.
</Warning>

## 런타임 저장소 CLI

### Acceptance loop

| 명령 | 주요 option | 성공/실패 의미 |
| --- | --- | --- |
| `acceptance-loop validate` | `--config` | suite 구조를 JSON 요약으로 출력한다. 설정 오류는 `2`다. |
| `acceptance-loop split` | `--config`, `--output-dir` | train/holdout 분리 manifest를 쓴다. |
| `acceptance-loop run` | `--config`, `--max-iterations`, `--baseline-ref`, `--restore-cmd` | 최종 score가 complete이면 `0`, incomplete이면 `1`, 잘못된 입력은 `2`다. |
| `acceptance-loop inspect` | `--run-dir` | 기존 run report를 출력한다. report가 없으면 `2`다. |

```bash
local-mogui-ade-orchestrator/scripts/acceptance-loop validate --config path/to/suite.json
local-mogui-ade-orchestrator/scripts/acceptance-loop run --config path/to/suite.json --max-iterations 3
```

### Dispatch gate

| 명령 | 주요 option | 출력/exit |
| --- | --- | --- |
| `dispatch-gate check` | 전역 `--ledger`; `--runtime`, `--model`, `--tier-policy`, `--tier-override`, `--no-record`, `--contract`, `--agents`, `--est-chars`, `--completion-channel` | JSON decision을 출력한다. allow면 `0`, deny면 `2`다. |
| `dispatch-gate register` | `--job-id`, `--probe-cmd`, `--contract-sha`, `--runtime`, `--orchestration-task`, `--tier-policy`, `--declared-model`, `--model-probe-cmd` | probe가 job id를 확인하고 orchestration completion channel이 검증되면 allow. 실패는 `2`다. |
| `dispatch-gate watch` | `--log`, `--max-idle` | log 상태 JSON을 출력한다. 정상 `0`, log missing `2`, stalled `3`이다. |
| `dispatch-gate report` | `--today` | ledger의 모델, denial, tier, policy, override 통계를 출력한다. ledger를 읽을 수 없으면 `2`다. |

`check`에서 `--completion-channel`이 있고 `--est-chars`가 없으면 contract 파일 길이를 추정값으로 사용한다. completion channel이 없으면 추정값을 `0`으로 두고 별도 gate 판정에 맡긴다.

### Master bootstrap, recovery, succession

| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `master-bootstrap` | `--charter`, `--handoff`, `--budget`, `--session-id`, `--strict-lease`, `--json` | charter/handoff 기반 bootstrap payload를 만든다. `BootstrapError`는 `2`다. |
| `master-bootstrap-live` | `--handoff-dir`, `--role-state-file`, `--budget`, `--bd`, `--charter-pointer` | SessionStart hook용 live bootstrap block을 출력한다. 내부 오류도 `[BOOTSTRAP-FALLBACK]`로 줄이고 항상 `0`을 반환한다. |
| `master-recover` | `--charter`, `--handoff`, `--ledger`, 반복 `--repo`, 반복 `--monitor-pattern`, `--session-id`, `--json` | recovery step report를 출력한다. |
| `master-succeed detect` | `text`, `--context-ratio`, `--json` | succession trigger를 분류한다. |
| `master-succeed handoff` | `--spec`, `--json` | JSON spec에서 thin handoff를 만든다. |
| `master-succeed verify-successor` | `--report`, `--json` | successor recovery report를 검증한다. |
| `master-succeed check-duplicates` | `--self-handle`, `--marker`, `--json` | 중복 master marker를 탐지한다. |
| `master-succeed retire` | `--self-handle`, `--expected`, `--target-handle`, `--target-pty-id`, `--target-session-id`, `--target-pid`, `--target-tty`, `--execute`, `--json` | predecessor terminal/session을 dry-run 또는 실제 close한다. |
| `master-succeed spawn` | `--workspace-selector`, `--expected-placement`, `--kickoff-text` 또는 `--kickoff-file`, `--root`, `--model`, `--agent`, `--title`, `--dry-run`, `--json` | successor terminal을 생성하거나 dry-run한다. agent별 기본 model이 없으면 `--model`이 필수다. placement mismatch는 fail-closed 계열 오류다. |

### 모델 식별과 drift 감사

| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `model-identity-probe` | `--transcript`, `--runtime`, `--config`, `--expect`, `--limit` | 기대 model이 없으면 정보 출력 후 `0`이고 아무 것도 assert하지 않는다. 기대 model과 최근 assistant turn이 모두 맞으면 `0`, drift/undecidable/설정 불가면 `2`다. |
| `model-drift-audit` | `--transcript`, `--session`, `--projects-dir`, `--workspace-dir`, `--expect`, `--ignore-synthetic`, `--json` | 단일 real model이면 `0`, transition 또는 기대값 mismatch면 `1`, transcript 없음/zero assistant turn/all synthetic이면 `2`다. |

`model-identity-probe`는 최근 tail sample을 본다. `model-drift-audit`는 세션 전체 assistant turn을 순회하므로 중간 model 전환을 잡는 용도다.

### 설정, redaction, template support

| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `workspace-descriptor-check` | `--path`, `--action`, `--config`, `--allow-unknown-repo`, `--json` | 허용 `0`, 금지 `1`, descriptor 미설정/invalid `2`다. config 해석은 명시 `--config`가 env보다 우선한다. |
| `redaction-scan.sh` | `--staged`, `--range A..B`, `--commit-messages A..B`, `--require-extra`, `--help` | clean `0`, findings `1`, missing tool/필수 rule 없음/usage/판단 불가 `2`다. |
| `redaction-inventory` | `--baseline`, `--min-count`, `--json` | uncovered 없음 `0`, uncovered 후보 있음 `1`, pattern file 없음 또는 git repo 아님 `2`다. |
| `generate-manifest` | `--skeleton`, `--out`, `--check`, `--stdout` | manifest 생성 또는 drift 검사. `--check`에서 stale이면 `1`, skeleton 미존재 등은 `2`다. |
| `codex-worker-pretrust` | worktree path, `--accounts-dir` | Codex 계정 설정에 worktree trust를 기록한다. TOML-capable interpreter가 없으면 skip을 출력하고 config를 건드리지 않는다. |
| `cursor-worker-pretrust` | worktree path, `--projects-dir` | Cursor Agent trust marker를 기록한다. JSON interpreter 검증 실패 시 marker를 쓰지 않는다. |
| `adapter doctor` | 없음 | adapter tool 존재 여부와 probe command를 JSON으로 출력한다. |
| `l1-digest tick` | `--config` | L1 digest 관찰 tick을 실행한다. |
| `next-version` | 없음 | 현재 release version 산출값을 출력한다. |
| `onboarding-preflight.sh` | `--fix`, env `PREFLIGHT_WAIVE` | onboarding 필수 도구를 측정한다. ready `0`, blocked `1`이다. |
| `worker-reap` | `--task-id` 또는 `--dispatch-id`, `--ledger`, `--dry-run`, `--json` | 성공 `0`; 누락 인자 `2`, dispatch 미종료 `3`, parse error `4`, 기타 실패 `1`이다. |

## Ops 저장소 CLI

### 작업자 dispatch와 Orca 운영

| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `dispatch` | `--contract`, `--spec`, `--terminal` 또는 `--worktree`, `--model`, `--runtime`, `--same-host-reason`, `--top-approved`, `--tier-policy`, `--est-chars`, `--transcript-glob`, `--check-only` | ops-side one-command dispatch 래퍼다. gate check, task create, terminal create/dispatch, register를 연결한다. |
| `orca-wait` | `--once`, `--timeout-ms`, `--types` | unread backlog를 ack-chain으로 drain한 뒤 `orca orchestration check`를 block wait한다. `orca`가 없으면 `127`이다. |
| `worker-pane-sweep` | 없음 | live Orca pane을 `working`, `idle`, `approval`, `start-screen`, `update`, `limit`, `shell`, `unknown`으로 분류한다. 조치가 필요한 pane이 있으면 non-zero다. |
| `dispatch-collision-check` | script 내부 parser | dispatch 중 terminal/worktree collision을 확인하는 보조 가드다. |
| `pr-steward-status` | PR 관련 인자 | PR steward 상태 확인용 래퍼다. |

`dispatch`는 master host runtime을 `MOGUI_MASTER_HOST_RUNTIME`, instance runtime config, fallback 순서로 해석한다. worker transcript glob은 runtime별로 다르며, `claude`는 worktree path에서 per-worker glob을 유도하고 다른 runtime은 불확실한 glob을 추정하지 않는다.

### 측정과 검증 보조 명령

| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `measure` | `<command> [args...]` | 실행한 명령의 `exit=<status>`를 첫 줄에 출력하고, 비어 있는 출력은 `(no output)`으로 표시한다. exit status는 원래 명령과 같다. 인자 없음은 `2`, `--help`는 `0`이다. |
| `spawn-test` | `[SCENARIO]`, env `SPAWN_TEST_RUNTIMES`, `SPAWN_TEST_BLOCKED`, `SPAWN_TEST_COORDINATOR_TERMINAL`, `SPAWN_TEST_COORDINATOR_RUN` | fresh install E2E harness다. `claude`와 `codex`는 must-pass floor이고, 실패 sandbox는 보존한다. |
| `harness-selfcheck.sh` | 없음 | harness 자체 점검용 shell script다. |
| `orca-surface-check.sh` | 없음 | Orca CLI surface drift를 확인한다. unchanged `0`, drift `1`, unmeasurable `2`다. |
| `compaction-probe.sh` | 없음 | compaction 관련 probe를 실행한다. |
| `hook-coverage-report` | 없음 | hook coverage report를 생성한다. |

### 템플릿 적용과 설치 drift

| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `template-check` | `--ops`, `--template`, `--json` | installed ops와 template manifest를 비교한다. current `0`, drift/behind/manifest absent로 비교 가능하지만 current가 아니면 `1`, 입력 누락/manifest malformed는 `2`다. |
| `template-apply` | `--ops`, `--template`, 반복 `--placeholder KEY=VALUE`, `--write`, `--json` | 항상 dry-run plan을 먼저 출력한다. 실제 write는 확인 문구 `apply`가 필요하며 `--yes`는 없다. manifest 미소유 path, instance-owned path, symlink escape를 거부한다. |
| `onboarding-rehearsal` | script parser | onboarding rehearsal 실행용 ops command다. |
| `workstream-render.sh` | script parser | workstream 문서/상태 렌더링 보조 명령이다. |

### PR과 대화 surface redaction

| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `pr-body-check` | `<pr-number>`, `--repo`, `--body-file`, `--template-file` | PR body의 필수 narrative section과 redaction pattern을 검사한다. 통과 `0`, section/redaction 실패 `1`, usage/runtime 오류 `2`다. |
| `conversation-redaction-scan` | `--repo`, `--limit` | GitHub PR body, PR comment, review body, issue body에서 home path 계열 redaction 위반을 찾는다. clean `0`, findings `1`, API/usage 오류 `2`다. |
| `test-tool-naming.sh` | 없음 | tool naming regression check다. clean `0`, findings `1`, usage/self-test failure `2`다. |

## 공개 surface 검증

### 문서 표와 실행 파일 surface 비교

`local-mogui-ade-orchestrator`의 표 검증은 실행 파일 인벤토리를 직접 측정한다.

```bash
cd local-mogui-ade-orchestrator
pytest -q tests/test_reference_command_table.py
```

검증 방식은 다음과 같다.

1. `scripts/` 바로 아래 실행 가능한 파일만 수집한다.
2. 각 script에 `--help`를 실행한다.
3. argparse usage에 `{a,b,c}` subcommand group이 있으면 `script subcommand`를 공개 surface로 기록한다.
4. subcommand group이 없으면 `script` 단일 명령으로 기록한다.
5. `docs/public/reference.md`의 command table row와 비교한다.
6. 실행 파일에는 있는데 문서 row가 없으면 `missing`, 문서에는 있는데 실행 파일이 없으면 `stale`로 실패한다.
7. fabricated gap canary로 `dispatch-gate check` row를 제거한 비교가 실제로 실패하는지도 테스트한다.

<Check>
현재 측정되는 런타임 저장소 공개 surface는 `acceptance-loop` 4개 subcommand, `dispatch-gate` 4개 subcommand, `master-succeed` 6개 subcommand, 그리고 단일 command script들을 포함한다.
</Check>

### Ops-side regression checks

`local-master-ops`는 제품 저장소처럼 중앙 reference table test를 갖지 않는다. 대신 script별 regression shell이 특정 운영 결함을 고정한다.

```bash
cd local-master-ops
./scripts/test-spawn-test.sh
./scripts/test-dispatch-runtime.sh
./scripts/test-measure.sh
./scripts/test-product-path-guard.sh
./scripts/test-seat-check.sh
./scripts/test-tool-naming.sh
```

| 테스트 | 고정하는 surface |
| --- | --- |
| `test-spawn-test.sh` | `spawn-test`의 runtime launch command와 report status 분류 |
| `test-dispatch-runtime.sh` | `dispatch`의 `agy` capability mapping과 approval flag |
| `test-measure.sh` | `measure`가 exit status를 첫 줄에 출력하고 원래 status를 보존하는 계약 |
| `test-product-path-guard.sh` | product path guard hook 동작 |
| `test-seat-check.sh` | seat check 동작 |
| `test-tool-naming.sh` | tool naming 규칙 위반 탐지 |

<Note>
prepared workspace에서 `local-master-ops`가 독립 git checkout으로 제공되지 않으면 `spawn-test` 계열 테스트는 `git rev-parse --show-toplevel` 단계에서 실행 환경 의존적으로 실패할 수 있다. 이 경우 script surface 문서화에는 영향을 주지 않지만, 실제 ops 저장소 checkout에서 다시 실행해야 한다.
</Note>

## Exit code 차이

| 범주 | `0` | `1` | `2` | 추가 code |
| --- | --- | --- | --- | --- |
| `dispatch-gate check/register` | allow | 사용하지 않음 | deny 또는 검증 실패 | `watch`는 stalled `3` |
| `acceptance-loop run` | final score complete | final score incomplete | config/value/report 오류 | 없음 |
| `workspace-descriptor-check` | allowed | prohibited | unconfigured/invalid/bad usage | 없음 |
| `model-identity-probe` | match 또는 no-expect informational | 사용하지 않음 | drift/undecidable/unconfigured | 없음 |
| `model-drift-audit` | no transition, expectation match | transition 또는 expectation mismatch | undecidable | 없음 |
| `redaction-scan.sh` | clean | findings | cannot decide | 없음 |
| `redaction-inventory` | uncovered 없음 | uncovered 후보 있음 | cannot decide | 없음 |
| `template-check` | current | drift/behind/checkable undetermined | malformed/unreadable input | 없음 |
| `template-apply` | dry-run clean 또는 write success | plan error/refused attempt | confirmation/input/write 판단 불가 | 없음 |
| `worker-reap` | success | other failure | missing args | dispatch not settled `3`, parse error `4` |
| `measure` | 원래 명령이 `0` | 원래 명령이 `1` | 인자 없음 또는 원래 명령이 `2` | 원래 명령 status 그대로 |
| `orca-wait` | wait 처리 성공 | unknown flag 또는 Orca wait 실패 status | Orca wait 실패 status | `orca` 없음 `127` |

## 문서 갱신 규칙

`local-mogui-ade-orchestrator:docs/public/reference.md`에 새 row를 추가할 때는 목적과 주요 option을 사람이 작성한다. command inventory는 generator가 아니라 테스트가 지킨다. 새 공개 script를 추가하면 같은 변경에서 다음 중 하나를 해야 한다.

<Steps>
<Step title="실행 파일 surface를 측정한다">
새 script가 실행 가능 bit를 갖고 `--help`를 제공하는지 확인한다. argparse subparser를 쓰면 usage의 `{subcommand,...}`가 문서 surface로 잡힌다.
</Step>

<Step title="reference table row를 추가한다">
`docs/public/reference.md`의 command table에 `scripts/<name>`과 실제 command 문자열을 추가한다. subcommand가 있으면 row를 subcommand별로 나눈다.
</Step>

<Step title="표 검증 테스트를 실행한다">
`pytest -q tests/test_reference_command_table.py`를 실행한다. `missing`은 실행 파일이 문서에 없다는 뜻이고, `stale`은 문서 row가 실제 script surface와 맞지 않는다는 뜻이다.
</Step>
</Steps>

## Related pages

<CardGroup>
<Card title="작업자 위임" href="/dispatch-workers">
`dispatch-gate check`, Orca task 생성, register probe, acceptance 전 재검증 흐름을 연결해 본다.
</Card>
<Card title="마스터 승계" href="/run-succession">
`master-succeed` subcommand가 succession trigger, handoff, successor verify, retire, spawn 단계에서 쓰이는 위치를 본다.
</Card>
<Card title="Redaction 게이트" href="/redaction-gates">
`redaction-scan.sh`, `redaction-inventory`, conversation surface scan의 범위와 실패 의미를 본다.
</Card>
<Card title="설정 참조" href="/configuration-reference">
`instance-runtime.json`, `workspace-descriptor.json`, model tier policy와 CLI override 해석 순서를 확인한다.
</Card>
</CardGroup>