Give your agent a CLI

The idea

Give the agent a small, predictable command-line interface to the system it is changing. Expose the actions a developer would otherwise perform by clicking through a UI, querying a database, or remembering a sequence of scripts.

The useful loop is simple: discover an action, execute it, inspect the resulting state, and check the outcome. A CLI makes that loop available in the same environment where the agent reads and edits code.

When it helps

Use this when an agent can implement a feature but struggles to exercise it. Local applications with fixtures, background jobs, or multi-step workflows are good candidates. Start with the workflow you repeatedly test by hand.

Put it into practice

1. Expose a narrow set of verbs and make --help explain them.
2. Provide structured output and meaningful exit codes.
3. Make state observable: return an ID that can be inspected.
4. Offer isolated fixtures and a repeatable local reset.
5. Make the target environment explicit before changing data.

The following is a proposed interface for an imaginary task app. It is not pstack syntax.

app --help
app fixtures load demo --env local
app tasks create --title "Review the patch" --json
# { "id": "task_42", "status": "open" }
app tasks complete task_42 --json
app tasks inspect task_42 --json
# { "id": "task_42", "status": "completed" }

Where it breaks down

A successful exit code does not prove the product works. Check the resulting state, and use browser checks for visual layout and interactions. Keep credentials out of output and distinguish local and production targets.

A CLI that hides errors or only emits unstructured logs leaves the agent guessing. Treat the interface as a product that both people and agents can use.

Connect the patterns

Pair this with SCENARIOS.md: the document describes the expected behavior; the CLI gives the agent a way to exercise it.