codewright (companion CLI)

A thin client over the Codewright public API v1 that runs on your machine. search and show only print information; run renders a recipe, requires explicit interactive confirmation before running anything destructive/requires_confirmation, and only ever executes the exact command you just confirmed — see docs/ARCHITECTURE.md's "Run time (MCP/skill)" model: Codewright describes commands, you decide whether to run them.

Install / usage

Once published, run it directly with npx, no install required:

npx @codewright/cli search "undo last commit"
npx @codewright/cli show git.undo_last_commit
npx @codewright/cli run git.undo_last_commit
npx @codewright/cli completion bash
npx @codewright/cli --version

During development in this monorepo, run it via the package script instead:

pnpm --filter @codewright/cli codewright search "undo last commit"
pnpm --filter @codewright/cli codewright show git.undo_last_commit
pnpm --filter @codewright/cli codewright run git.undo_last_commit
pnpm --filter @codewright/cli codewright completion bash
pnpm --filter @codewright/cli codewright --version

codewright search <query>

Calls GET /api/v1/recipes/search?q=... and prints matching recipes (id, risk, title, summary).

$ codewright search "undo last commit"
1 result(s) for "undo last commit":

git.undo_last_commit  (low)
  Undo the last commit
  Keeps your changes staged, removes the commit itself.

codewright show <id> [--platform macos|linux|windows]

Calls GET /api/v1/recipes/{id} and renders the commands, verification steps, and undo path for your detected platform. Pass --platform to override auto-detection (based on process.platform, mapped to the recipe schema's macos/linux/windows).

$ codewright show git.undo_last_commit
Undo the last commit  (git.undo_last_commit v1)
Keeps your changes staged, removes the commit itself.

Risk: low

Commands (macos):
  1. git reset --soft HEAD~1
     Removes the last commit, keeps changes staged (low)

Verification:
  $ git log -1 --oneline
    expect: shows the previous commit as HEAD

Undo:
  1. git commit -c ORIG_HEAD
     Restores the undone commit

codewright run <id> [--platform macos|linux|windows]

Prompts for any declared parameters (blank input falls back to the recipe's default), calls POST /api/v1/recipes/{id}/render to substitute them, and prints the resulting commands and risk level.

If the rendered response says requires_confirmation — always true for destructive recipes, per docs/RECIPE_SPEC.md — you must type y/yes at an explicit prompt before anything runs. Any other answer aborts with no commands executed. Codewright's own process only ever executes the exact command string it just showed you and you just confirmed; it never constructs or infers commands of its own.

Commands then run locally in your shell, one at a time, stopping immediately if one exits non-zero. After a successful run, each of the recipe's documented verification steps is executed and its output shown, and you're asked to confirm whether it matches the expected result — the CLI reports a pass/fail summary per step (via its exit code: non-zero if the run was aborted or any verification step didn't match).

$ codewright run git.hard_reset
Risk: destructive
  git reset --hard  — Discard all local changes

This recipe is "destructive" risk and requires confirmation before running:
  1. git reset --hard
Proceed? [y/N] y
$ git reset --hard
HEAD is now at abc1234 ...
Verifying: $ git status --short
Expected: no output (working tree clean)
Did the output match? [y/N] y
  ✓ verified

codewright diagnose <workflow_id> [--platform macos|linux|windows]

Drives a workflows/<category>/<slug>.yaml decision tree (docs/WORKFLOW_INTERPRETER_SPEC.md) from its entry node to a terminal outcome. Where run executes a single recipe, diagnose is diagnosis-then-routing: it runs read-only diagnostic checks locally, branches on their output, and — for any recipe_ref node the workflow routes into — drives that recipe through the exact same confirm/execute/ verify path run uses, unmodified. The interpreter never decides on its own whether a step needs confirmation; that is always the referenced recipe's own risk/requires_confirmation contract.

codewright diagnose git.cant_push_branch

Loads workflows/ and recipes/ from the current working directory, validates them (the same static checks workflows:validate runs), then finds the workflow by id and interprets it:

• diagnostic nodes run their command locally with no confirmation prompt (diagnostic risk is capped at read_only/low by the schema), concatenate stdout+stderr, and take the first branch whose match regex tests true against the combined output, in declaration order — falling back to the branch's required default if none match.
• recipe_ref nodes run the referenced recipe through the same confirm → execute → verify path as codewright run <id>, then branch on the derived outcome: success (the recipe completed and every verification step was confirmed as matching) or outcome: failure (declined, a command failed, or any verification step didn't match).
• outcome nodes are terminal: diagnose prints the node's summary (and any related recipe ids, for a needs_human_choice outcome — run one of the named ids directly with codewright run <recipe_id>), then stops. The process exits non-zero unless the terminal outcome was success.

Constraints (see docs/WORKFLOW_INTERPRETER_SPEC.md for the full rationale):

• No resume. Every invocation starts fresh at entry; there is no persisted run state. If a run is interrupted, re-run the command.
• Visit cap of 3. Any single node may run at most 3 times within one execution (a runtime safety net for a workflow that legitimately loops, e.g. re-checking a diagnostic after a fix attempt); a 4th visit aborts the run with a message naming the node.
• Not configurable in this slice: the visit cap has no CLI flag, and there is no first-class exit-code branch condition — only output-text matching.

codewright completion <bash|zsh>

Prints a shell completion script for the given shell.

codewright completion bash > /etc/bash_completion.d/codewright
codewright completion zsh > "${fpath[1]}/_codewright"

codewright --version / -v

Prints the installed CLI version.

codewright help

Prints usage and your detected platform/shell.

Configuration

• CODEWRIGHT_API_BASE_URL — override the API base URL (defaults to https://codewright.tools/api/v1). Useful for pointing at a local or staging deployment while developing. The same env var name is used by @codewright/mcp and the agent skill.

Scope

• search/show only print information — they never execute a command, write a file, or shell out.
• run is the one command that executes anything, and only after an explicit interactive confirmation on destructive/requires_confirmation recipes; it never runs anything the user didn't just confirm.
• No auth: these endpoints are the public, unauthenticated API v1 surface.

Development

pnpm --filter @codewright/cli typecheck
pnpm --filter @codewright/cli test
pnpm --filter @codewright/cli build