How to Use the Kane CLI Generate Flow

kane-cli generate follows a simple loop: generate → refine → save → run. Each command is one turn that exits when it finishes, and the request id links the turns together. This page walks through the whole loop. For an overview of the feature and the option reference, see Generating test cases with AI.

1. Generate

Start with a plain-language description of what you want covered:

kane-cli generate "checkout flow on a shopping site"

Kane CLI generates scenarios and cases and prints them. The output ends with a request id and the exact commands to refine or save the result:

✓ Generated 3 scenarios · 11 cases  (request 23271)

▸ Login
   - Valid credentials [Positive]
   - Wrong password [Negative]
   - Empty fields [Edge]
▸ Checkout
   - Guest checkout [Positive]
   - Expired card [Negative]
   ...

  Refine:  kane-cli generate "<refinement>" --refine --req 23271
  Save:    kane-cli generate --save --req 23271

Keep the request id. Every later command uses it. To get a smaller or larger set, set limits on its size:

kane-cli generate "checkout flow on a shopping site" --scenario-limit 4 --per-scenario-limit 6

Add --memory to reuse relevant existing cases and avoid duplicating coverage you already have. To give the generator more context, attach local files such as a spec, a screenshot, a PDF, or a CSV with --files. This works on a new generation or a refine:

kane-cli generate "cover the flows described in the attached spec" --files ./spec.pdf,./flows.csv

You can attach up to 10 files, each 50 MB or smaller: documents, images, audio, or video. Kane CLI validates all paths before it sends anything. See Attaching files for context.

2. Refine

You refine a set by describing changes in plain language. Each refine is a separate command with --refine --req <id>:

kane-cli generate "also cover an expired card and an out-of-stock item" --refine --req 23271
kane-cli generate "drop the social-login scenario, focus on guest checkout" --refine --req 23271

Each refine returns the updated result. Repeat until the set looks right.

When generation asks a question

Sometimes a turn ends with a question instead of a result, for example “Which environment should these target, staging or production?” This is a normal outcome, not a failure, and the command exits 0. To answer, run a refine with your answer:

kane-cli generate "target staging" --refine --req 23271

If a script or agent drives the loop, add --agent, which also turns on automatically when stdin is not a TTY. Read the signal that an answer is needed from the NDJSON output, then answer with a refine in the same way.

3. Save

When the set looks right, save it. --save writes the functional cases as _test.md files:

kane-cli generate --save --req 23271

By default this writes under <cwd>/.testmuai/tests:

.testmuai/tests/
  checkout-23271/
    login/
      valid-credentials_test.md
      wrong-password_test.md
    checkout/
      guest-checkout_test.md
      ...

Choose a different location with --out, and name the suite with --name:

kane-cli generate --save --req 23271 --out ./tests --name checkout-suite

Only functional cases are written. Non-functional cases (Security, Performance, and so on) appear in the generated result but are not saved as runnable tests. See Saving is functional-only.

4. Run

The saved files are ordinary _test.md tests. Run any of them with testmd:

kane-cli testmd run .testmuai/tests/checkout-23271/checkout/guest-checkout_test.md

Everything in the testmd docs applies from here: replay from cache, edit steps, compose tests with @import, and commit the output to git.

Automating it (agents / CI)

Pass --agent to get structured NDJSON on stdout instead of the human-readable display, so a script or coding agent can drive the loop. The flag turns on automatically when stdin is not a TTY:

kane-cli generate "checkout flow on a shopping site" --agent
kane-cli generate "add an expired-card case" --refine --req 23271 --agent
kane-cli generate --save --req 23271 --agent

Each command prints one JSON object per line. The last line is the final event, with the request id, the status, and the refine and save commands to run next.

Exit codes

Code	Meaning
`0`	Turn completed, including a turn that ended with a clarification question
`1`	Generation failed
`2`	Error: authentication, setup, or transport, or an invalid combination of flags
`3`	Generation stopped or cancelled
`130`	Interrupted (Ctrl-C)

An invalid flag combination exits 2 with a message that explains the fix. Examples: --refine without --req, a description with --save, --out without --save, or --req without --refine or --save.

Next steps

Generating test cases with AI: overview, modes, and the full option reference.
Running tests with testmd: run and replay the files --save produces.

​1. Generate

​2. Refine

​When generation asks a question

​3. Save

​4. Run

​Automating it (agents / CI)

​Exit codes

​Next steps