Use cases

From intent to working code.

Six ways to work with Matcha CLI, from a first plan to the final test.

Six workflows. One considered approach.

Artwork illustrates workflows. CLI examples and test results are illustrative, not product screenshots or verified runs.

Build a feature

You know what needs to change. Now bring it into the repository and check that it works.

An exploded architectural assembly with a green component aligned to fit between pale structural platforms. — Requests
Rate limiter
Handler
A deliberate addition to an existing flow.

Start with a prompt

Add rate limiting to the API and cover it with tests.

How the work unfolds

Read the handler and its tests to understand the existing behavior.
Add the rate limiter and tests for requests within and beyond the limit.
Run the tests, inspect the results, and review the diff.

What you leave with

A focused change, with tests that exercise the new behavior.

Explore the CLI example

Illustrative CLI example

Matcha CLI

Add rate limiting to the API and cover it with tests.

Reading src/api/route.ts and src/api/route.test.ts

- export const POST = handler+ export const POST = withRateLimit(handler)

Illustrative result: rate limiting added; 12 tests passed.

Plan the change

The destination is clear, but the route deserves a little thought before you start editing.

Translucent architectural plans and connected modules viewed from above, with one route marked in green. — Inspect
Propose
Review
Make the approach visible before editing.

Start with a prompt

/plan Move auth from cookies to JWT. Do not edit yet.

How the work unfolds

Enter plan mode with /plan, or start the planning turn with /plan <description>.
Read the authentication flow and outline the migration, its tradeoffs, and tests.
Review the proposed steps before moving on to implementation.

What you leave with

An approach you can inspect before the code changes.

Explore the CLI example

Illustrative CLI example

Matcha CLI

/plan Move auth from cookies to JWT. Do not edit yet.

Reading src/auth.ts and src/middleware.ts

1. Map session handling and migration risks.2. Propose token validation and regression tests.

Plan ready for review. Files have not been edited.

Fix a failing test

A failing test gives you a starting point. Follow it back to the behavior that needs to change.

Two architectural assemblies side by side: one has a displaced component, and the other is precisely aligned. — Failure
Targeted fix
Rerun
Keep the assertion. Correct the behavior.

Start with a prompt

Fix the failing auth test and run it. Keep the expiry-boundary assertion.

How the work unfolds

Inspect the failure: a session should expire exactly at its expiry time.
Correct the comparison in the implementation, keeping the boundary assertion.
Rerun the authentication tests and inspect the result.

What you leave with

The underlying behavior corrected, with the regression test preserved.

Explore the CLI example

Illustrative CLI example

Matcha CLI

Fix the failing auth test. Keep the expiry-boundary assertion.

Failure: session remains valid when now equals expiresAt. Reading src/auth.ts.

- const expired = expiresAt < now;+ const expired = expiresAt <= now;

Illustrative result: 3 auth tests passed; the boundary assertion is unchanged.

Change models, keep working

You want another configured model to take the next turn, within the same session.

Interchangeable frosted-glass lenses standing along a continuous green path. — Same session
Selected model
Continue
A new perspective on the work already in progress.

Start with a prompt

/model <name>

How the work unfolds

Choose a model available through a provider you have configured.
Replace <name> with its model ID or display name. Bare /model shows usage.
Continue the work in the same session with the selected model.

What you leave with

A different model for the next step, with the session still open.

Explore the CLI example

Illustrative CLI example

Matcha CLI

/model <name>

Replace <name> with an available configured model ID or display name.

Session · current workNext turn · selected configured model

Illustrative flow: continue in the same session. Bare /model shows usage.

Follow project conventions

Your repository already explains how to work in it. Start from those shared conventions.

Layered paper sheets and a translucent plane aligned to one precise structural grid. — Project rules
Context
Consistent work
AGENTS.md · CLAUDE.md · Cursor rules

Start with a prompt

Keep going in this repo. Follow the project rules.

How the work unfolds

Read the available AGENTS.md, CLAUDE.md, and Cursor rules.
Use the relevant conventions to guide the implementation and checks.
Review the change in the context of how this project is built.

What you leave with

Work informed by the conventions already in your repository.

Explore the CLI example

Illustrative CLI example

Matcha CLI

Keep going in this repo. Follow the project rules.

AGENTS.md
CLAUDE.md
.cursor/rules

Reading available repository instructions.

Context · project conventionsChange · follows the relevant instructions

Illustrative flow: apply the repository’s conventions to the task.

Run a task from a script

A task belongs in the command or script you already use. Give it a prompt and collect the result.

Three architectural objects arranged in a linear sequence, connected by a narrow green strip. — Prompt
Local CLI work
Result + exit
One prompt in. A result to work with.

Start with a prompt

matcha -p "fix the failing auth test and run it"

How the work unfolds

Pass a prompt to matcha -p from your command or script.
The CLI works locally, using the tools and permissions available to the run.
Read the printed result when the turn completes and the process exits.

What you leave with

One CLI turn that fits into your existing script.

Explore the CLI example

Illustrative CLI example

Matcha CLI

matcha -p "fix the failing auth test and run it"

Inspecting the expiry-boundary failure in src/auth.test.ts and src/auth.ts.

- const expired = expiresAt < now;+ const expired = expiresAt <= now;

Illustrative result: 3 tests passed. Result printed; process exits.

Matcha CLI

Your next task starts here.

Open your repository. Bring a clear intention. Take the next step with Matcha CLI.

Get started

Matcha CLI runs locally, with sessions and rules on your machine. Model requests go to your chosen provider. MatchaCode requires no account and has no official cloud.