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, and only ever executes the exact command you just confirmed.

Install / usage

Run it directly with npx, no install required:

$npx @codewright/cli search "undo last commit"

Commands

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 commands, verification steps, and undo path for your detected platform.

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

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

Prompts for declared parameters, renders the recipe, and — for destructive/requires_confirmation recipes — requires an explicit y/yes before anything runs. Only ever executes the exact command it just showed you.

codewright run git.discard_local_changes

Risk: destructive

git status --short — Review exactly which changes will be discarded

git restore --staged . — Unstage everything so all changes are visible to the next step

git restore . — Discard all uncommitted changes in tracked files

This recipe is "destructive" risk and requires confirmation before running:

1. git status --short

2. git restore --staged .

3. git restore .

Proceed? [y/N] y

$ git status --short

M README.md

$ git restore --staged .

$ git restore .

Verifying: $ git status --short

✓ verified

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

Drives a workflows/<category>/<slug>.yaml decision tree from its entry node to a terminal outcome — diagnostic nodes run read-only checks, recipe_ref nodes run the referenced recipe through the same confirm/execute/verify path as run, and outcome nodes are terminal.

codewright diagnose git.cant_push_branch

codewright completion <bash|zsh>

Prints a shell completion script for the given shell.

codewright completion bash > /etc/bash_completion.d/codewright

codewright --version / -v

Prints the installed CLI version.

codewright --version

codewright help

Prints usage and your detected platform/shell.

codewright help

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.

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. There is no auth: these endpoints are the public, unauthenticated API v1 surface.