How to Use Kane CLI Agent Mode

Agent Mode outputs structured NDJSON instead of the interactive terminal UI. It’s how AI coding agents (Claude Code, Codex CLI, Gemini CLI) consume Kane CLI results: parse events programmatically, extract the final result, and present it to the user.

Enable Agent Mode

Add --agent to any run command:

kane-cli run "Verify the checkout flow completes successfully" \
  --url https://myapp.com \
  --agent \
  --headless

When --agent is active:

The interactive TUI is fully suppressed (no boot screen, no menus)
stdout carries only NDJSON, one JSON object per line, and the progress UI goes to stderr
When stdin is not a TTY, Kane CLI turns off ask_user, so the run never stops to wait for input (see below)

Kane CLI also switches to NDJSON on its own when stdin is not a TTY, for example in CI. Pass --agent anyway, so the output format does not depend on how the shell is set up.

Add --headless wherever there is no display, such as CI runners, containers, and SSH sessions, to avoid display server errors. On a desktop, a coding agent can leave the browser visible so you can watch the run.

NDJSON Output Format

With --agent, Kane CLI writes one JSON object per line (NDJSON) to stdout. Every line carries v, the stream contract version (currently 1), and ts, the time the line was written. Here is a shortened kane-cli run stream. ... marks lines and values left out, and the run_end line shows only some of its fields:

{"type":"stream_start","cli_version":"0.9.0","surface":"run","pid":16664,"v":1,"ts":"2026-10-15T08:47:26.889Z"}
...
{"type":"bifurcation","flows":["Navigate to https://example.com then verify the page heading says Example Domain"],"count":1,"v":1,"ts":"2026-10-15T08:47:39.435Z"}
{"step":2,"status":"running","remark":"Step 1","v":1,"ts":"2026-10-15T08:47:39.957Z"}
{"step":2,"status":"done","remark":"navigate: Navigate to https://example.com","v":1,"ts":"2026-10-15T08:47:39.958Z"}
...
{"step":4,"status":"done","remark":"assert: the page heading says Example Domain","v":1,"ts":"2026-10-15T08:47:54.260Z"}
{"type":"run_end","status":"passed","summary":"...","reason":"Objective completed","duration":20.5,"credits_consumed":11.9,"test_url":"https://test-manager.lambdatest.com/...","session_dir":"...","v":1,"ts":"2026-10-15T08:48:10.211Z"}

Rules for parsing the stream:

The first line is stream_start. Its surface is run, testmd, or testrun, and cli_version names the Kane CLI release that wrote the stream.
On a run stream, step lines have no type field. A step prints a running line when it starts and a done or failed line when it ends, and the stream has no run_start, step_start, step_event, or step_end events. A testmd run stream is different: every line is typed, and each test_md_step_start and test_md_step_end pair wraps typed run_start, step_start, step_event, step_end, and run_end events for that step.
Ignore fields and event types you do not recognize. New ones can appear in any release without a change to v. Skip any line that is not JSON.
For a run that started, the last line is run_end. A run refused before it starts can exit with code 2 and no run_end line, so check the exit code first.

Kane CLI also writes the same lines to events.ndjson in the session folder while the run is in progress.

NDJSON Event Schema

The tables below describe a kane-cli run stream. A testmd run stream is typed on every line and ends with test_md_done, and a testrun run stream uses its own testrun_* events. See Command-Specific Completion.

Step Progress Lines in a `run` Stream

Field	Type	Description
`step`	number	Step index. It can run one ahead of the step a person would count, because a `bifurcation` takes the first slot. To report steps taken, count the `done` and `failed` lines
`status`	string	`running` when the step starts, then `done` or `failed` when it ends
`remark`	string	What the agent did, or why the step failed

Typed Events in a `run` Stream

Type	Key Fields	Description
`stream_start`	`cli_version`, `surface`, `pid`	The first line of every stream. `session_dir` may also be present
`project_folder_auto_defaulted`	The project and folder Kane CLI chose (ID and name)	No Test Manager project or folder was configured, or the saved one was no longer valid, so Kane CLI picked one. Sent before the first step line
`bifurcation`	`flows[]`, `count`	The agent split the objective into sub-flows
`child_agent_start`	`child_id`, `objective`, `parent_step`	A child agent started
`child_agent_end`	`child_id`, `success`, `steps_taken`, `summary`	A child agent finished
`ask_user`	`question`, `step_index`, `options` (optional)	The agent needs input (turned off automatically when stdin is not a TTY)
`warning`	`code`, `message`, `suggested_file`, `variables[]`	A non-fatal warning, sent before the first step line (for example `code: "unresolved_variables"`)
`error`	`message`	An error occurred
`run_end`	(see below)	The final event of a `run` that started: always the last line

Unresolved-Variable Warning

Kane CLI checks every {{name}} in the objective before the run starts. If a name has no value, Kane CLI prints a warning and the run continues. The name is typed literally as written, unless a step sets its value first. With --agent, the warning is a single typed event, sent before the first progress event:

{"type":"warning","code":"unresolved_variables","message":"2 variable(s) have no value — typed as written unless a step sets them first","suggested_file":".testmuai/variables/variables.json","variables":[{"name":"checkout_url","reason":"not_declared","used_by":[{"file":"objective","step":1}]},{"name":"login_password","reason":"value_missing","file":".testmuai/variables/variables.json","used_by":[{"file":"objective","step":1}]}]}

reason is value_missing, not_declared, or not_a_dataset_column. The warning does not change the exit code. See Unresolved variables for what each reason means and which names are never checked.

The `run_end` Event

run_end is the last line of a kane-cli run that started, and it carries the complete result. A run refused before it starts, for example with no start URL, no sign-in, or no Chrome, can exit with code 2 and no run_end line. Check the exit code first, then read run_end.

{
  "type": "run_end",
  "status": "passed",
  "summary": "Searched for laptop and added first result to cart",
  "one_liner": "Searched for laptop on Amazon and added to cart",
  "reason": "Objective completed",
  "duration": 45.2,
  "credits_consumed": 11.9,
  "final_state": {
    "price": "$29.99",
    "product_name": "Wireless Headphones"
  },
  "test_url": "https://test-manager.lambdatest.com/projects/123/test-cases/456",
  "session_dir": "~/.testmuai/kaneai/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "v": 1,
  "ts": "2026-10-15T10:31:30.412Z"
}

run_end can carry more fields than this example, such as context and result_code. Ignore the fields you do not need.

`run_end` Fields

Field	Description
`status`	`"passed"` or `"failed"`
`summary`	What the agent did
`one_liner`	A short, single-sentence summary for display
`reason`	A short label for why the run stopped, such as `"Objective completed"`
`duration`	Run time in seconds
`credits_consumed`	Credits the run used, as a decimal number, when reported. Round it for display. Older releases called this field `credits`
`final_state`	Values saved with “store … as” in the objective
`test_url`	Link to the test case in Test Manager. Present when the upload succeeded
`session_dir`	The session folder. The sealed evidence pack is in its `evidence/` subfolder
`run_dir`	Legacy. The folder it names is no longer created: run logs and screenshots are in the evidence pack
`result_code`	Optional machine classification of the result. See Error Codes. With `--bug-detection`, a confirmed product bug arrives as `result_code` `740` with a `verdict` object
`condition_results`	`--analyzer-only` runs only: `boolean[]`, one verdict per `--condition`, in order. See Assertion controls and current-page analysis

Exit Codes for `kane-cli run`

Code	Meaning
`0`	The run passed
`1`	The run went ahead and did not pass, or the upload failed. Read the failing step’s `remark` and the evidence pack to tell a product bug from a test problem
`2`	The run did not start, and no credits were used: sign-in, configuration, no start URL, Chrome, network, or an unknown subcommand. There may be no `run_end` line
`3`	The run was canceled or hit `--timeout`

testmd run, testrun run, generate, and the assurance commands have their own exit codes. See CLI Reference: Exit Codes.

The Evidence Pack for Each Run

Every run seals an evidence pack: one .evidence file, a standard zip, that holds the test definition, a result summary, per-step screenshots (plus annotated copies that highlight the element the agent acted on), per-step browser console and network logs, run logs, and, when a step fails, a failure record for that step. The pack holds no video.

Command	Where the sealed pack is
`kane-cli run`	In the `evidence/` subfolder of `session_dir`. It is also copied to `.testmuai/evidence/` in your working directory when you name the run with `--name`
`kane-cli testmd run`	Copied to `.testmuai/evidence/` on every run
`kane-cli testrun run`	Created directly in `.testmuai/evidence/`

run_end has no field for the pack’s path. After the run, Kane CLI prints a hint line on stderr, not on stdout:

evidence: view locally with `kane-cli evidence serve <path-to-pack>`

kane-cli evidence serve serves sealed packs from your machine to the hosted viewer and uploads nothing. See Evidence Packs and How to Debug a Failed Kane CLI Run.

Parsing the `run_end` Result in a Script

Save stdout to a file, read the exit code, then pick the run_end line by its type. Selecting by type keeps the script working when a run never started and has no run_end line.

kane-cli run "Go to https://example.com, store the page heading as 'heading', then verify it says Example Domain" \
  --agent --headless > run.ndjson
code=$?
echo "exit code: $code"   # 2: the run did not start, and there may be no run_end line

# The full result
jq -cR 'fromjson? | select(.type == "run_end")' run.ndjson

# Just the status
jq -rR 'fromjson? | select(.type == "run_end") | .status' run.ndjson

# A value saved with "store ... as 'heading'"
jq -rR 'fromjson? | select(.type == "run_end") | .final_state.heading' run.ndjson

fromjson? skips any line that is not JSON. When the run started, run_end is also the last line, so tail -n 1 run.ndjson returns it too.

Command-Specific Completion

Reading the last run_end event works for one-shot run only. Other commands end with their own completion event:

testmd run: read test_md_done for overall_status, duration_s, session_id, and the optional share_url. The stream can also contain run_end events; these finish individual steps, not the file.
Local testrun run suites: end with testrun_done. Suites dispatched to the remote grid then also emit remote_done; keep its status, exit, and sessions_path fields.
generate: ends with generate_done.
Assurance commands: conversational agent streams end with done. The review and read commands have their own completion contracts.

Always check the process exit code too: an early refusal, an invalid plan, or a dry run can exit without the normal completion event. Progress events are meant for live display. When you count completions, count only done and failed. Step indices can repeat, so keep track of which child agent and execution each event belongs to. testrun run prints its NDJSON stream when stdin is not a TTY, or when you pass --agent. See Batch runs (testrun).

Handling `ask_user` Events

If an objective requires user input mid-run, Kane CLI fires ask_user:

{"type": "ask_user", "question": "Which item should I select?", "options": ["Small", "Medium", "Large"]}

ask_user is turned off automatically when stdin is not a TTY. In CI/CD and AI agent contexts, stdin is never a TTY, so ask_user never fires. Write objectives that don’t require interactive prompts.

If stdin IS a TTY, respond by writing JSON to stdin:

{"type": "user_response", "answer": "Medium"}

To cancel:

{"type": "cancel"}

Agent Mode vs Interactive Mode

	Agent Mode (`--agent`)	Interactive Mode
TUI	Suppressed	Full terminal UI
Output	NDJSON to stdout	Formatted text
Stderr	Progress UI and hint lines, such as the evidence pack path	Logs + progress UI
Use case	AI agents, programmatic tools	Human development

Next Steps

Error Codes: Complete reference of result_code values and recommended actions
Evidence Packs: What every run captures and how to view it
Parallel Execution: Run multiple tests concurrently
Skills: Install the Kane CLI skill for Claude, Codex, or Gemini
CLI Reference: Full flag and command reference
Skill parsing reference: The NDJSON schema the Kane CLI skill follows

​Enable Agent Mode

​NDJSON Output Format

​NDJSON Event Schema

​Step Progress Lines in a run Stream

​Typed Events in a run Stream

​Unresolved-Variable Warning

​The run_end Event

​run_end Fields

​Exit Codes for kane-cli run

​The Evidence Pack for Each Run

​Parsing the run_end Result in a Script

​Command-Specific Completion

​Handling ask_user Events

​Agent Mode vs Interactive Mode

​Next Steps

Enable Agent Mode

NDJSON Output Format

NDJSON Event Schema

Step Progress Lines in a `run` Stream

Typed Events in a `run` Stream

Unresolved-Variable Warning

The `run_end` Event

`run_end` Fields

Exit Codes for `kane-cli run`

The Evidence Pack for Each Run

Parsing the `run_end` Result in a Script

Command-Specific Completion

Handling `ask_user` Events

Agent Mode vs Interactive Mode

Next Steps