156 lines
4 KiB
Markdown
156 lines
4 KiB
Markdown
---
|
|
title: CLI
|
|
description: Local patch.moi commands for setup, maintenance runs, status, retry, replay, and sync.
|
|
---
|
|
|
|
# CLI
|
|
|
|
Run the CLI from the repository root:
|
|
|
|
```bash
|
|
bun run patch.moi -- status
|
|
```
|
|
|
|
By default, the CLI writes and reads patch.moi product state under `DATA_DIR`
|
|
relative to the workspace root. Use `--data-dir` to point at another JSONL
|
|
state directory and `--json` for machine-readable output.
|
|
|
|
## Setup
|
|
|
|
Inspect the neighboring Codex fork checkout:
|
|
|
|
```bash
|
|
bun run patch.moi -- setup codex --json
|
|
```
|
|
|
|
Add the canonical OpenAI upstream remote when it is missing:
|
|
|
|
```bash
|
|
bun run patch.moi -- setup codex --apply
|
|
```
|
|
|
|
The setup command reports the current branch, `origin`, `upstream`, worktree
|
|
cleanliness, and whether the checkout is ready for an automated maintenance
|
|
run. It does not clean local changes.
|
|
|
|
## Patch Branches
|
|
|
|
Patch branch commands operate on a local fork workspace. They do not push.
|
|
|
|
Inspect whether a workspace has the expected `main`, `upstream`, and
|
|
`patch/*` branches:
|
|
|
|
```bash
|
|
bun run patch.moi -- patch doctor --repo ../codex --json
|
|
```
|
|
|
|
List ordered local patch branches:
|
|
|
|
```bash
|
|
bun run patch.moi -- patch list --repo ../codex
|
|
```
|
|
|
|
Capture a feature branch as a single patch branch commit:
|
|
|
|
```bash
|
|
bun run patch.moi -- patch capture patch/010-packaging-build \
|
|
--repo ../codex \
|
|
--from packaging-work \
|
|
--base main \
|
|
--message "patch: packaging and release build"
|
|
```
|
|
|
|
Rebuild the maintained `main` branch from `upstream` plus all ordered
|
|
`patch/*` branch tips:
|
|
|
|
```bash
|
|
bun run patch.moi -- patch rebuild --repo ../codex --base upstream --to main
|
|
```
|
|
|
|
If a cherry-pick conflicts, rebuild stops with `needs_intervention` and leaves
|
|
the checkout in the conflicted state for the operator or a Code Mode turn.
|
|
|
|
## Run Maintenance
|
|
|
|
Dispatch the harness release fixture through the patch.moi state path:
|
|
|
|
```bash
|
|
CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 \
|
|
bun run patch.moi -- run harness
|
|
```
|
|
|
|
The command records the flow event, dispatch record, and maintenance attempt
|
|
under `DATA_DIR`. If `PATCH_WORKSPACE_BACKEND_URL` is unset, the dispatch uses
|
|
local flow execution from the workspace root. If it is set, the dispatch goes to
|
|
the configured workspace backend.
|
|
|
|
Verify Codex release flow matching without executing release work:
|
|
|
|
```bash
|
|
bun run patch.moi -- run codex-release --tag rust-v0.130.0 --dry-run
|
|
```
|
|
|
|
Verify Codex upstream main update matching without executing branch maintenance:
|
|
|
|
```bash
|
|
bun run patch.moi -- run codex-main \
|
|
--sha '<upstream-main-sha>' \
|
|
--dry-run
|
|
```
|
|
|
|
Dispatching the Codex release task requires an explicit execution surface. Use
|
|
Actions/local mode when no workspace backend is running:
|
|
|
|
```bash
|
|
CODEX_WORKSPACE_MODE=actions \
|
|
bun run patch.moi -- run codex-release --tag rust-v0.130.0
|
|
```
|
|
|
|
Or point at a workspace backend:
|
|
|
|
```bash
|
|
PATCH_WORKSPACE_BACKEND_URL=ws://127.0.0.1:3586 \
|
|
bun run patch.moi -- run codex-release --tag rust-v0.130.0
|
|
```
|
|
|
|
Use `--allow-local` only when you intentionally want the local Patch process to
|
|
execute matching Codex release flows. The Code Mode step still requires its own
|
|
`CODEX_FLOWS_MODE=code-mode` gate.
|
|
|
|
## Status
|
|
|
|
Read patch.moi-owned state:
|
|
|
|
```bash
|
|
bun run patch.moi -- status
|
|
bun run patch.moi -- events --type upstream.release
|
|
bun run patch.moi -- dispatches --status failed
|
|
bun run patch.moi -- attempts --status needs_intervention
|
|
```
|
|
|
|
These commands inspect JSONL state. They do not reach into Git or a workspace
|
|
backend unless a command explicitly dispatches, replays, or syncs.
|
|
|
|
## Retry, Replay, And Sync
|
|
|
|
Retry dispatch transport failures:
|
|
|
|
```bash
|
|
bun run patch.moi -- retry '<event-id>'
|
|
```
|
|
|
|
Replay an accepted event to create another backend attempt:
|
|
|
|
```bash
|
|
bun run patch.moi -- replay '<event-id>'
|
|
```
|
|
|
|
Sync the latest workspace run outcome and candidate refs into the patch.moi
|
|
maintenance attempt:
|
|
|
|
```bash
|
|
bun run patch.moi -- sync '<attempt-id>'
|
|
```
|
|
|
|
Retry and replay append new dispatch and maintenance-attempt records. Sync
|
|
appends a newer record for the same attempt id when backend run state changes.
|