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)
Stdin is not used (no interactive prompts)

Always combine --agent with --headless in non-interactive environments (CI/CD, agent contexts) to avoid display server errors.

Output Format

Kane CLI outputs one JSON object per line (NDJSON) to stdout:

{"type":"run_start","objective":"Verify checkout","timestamp":"2026-04-14T10:30:45Z"}
{"type":"step_start","index":0,"objective":"Navigate to cart page"}
{"type":"step_event","index":0,"event":"action","detail":"Navigated to /cart","success":true}
{"type":"step_event","index":0,"event":"screenshot","detail":"Screenshot captured"}
{"type":"step_end","index":0,"status":"passed","duration":2.3,"summary":"Navigated to cart"}
{"type":"step_start","index":1,"objective":"Click checkout button"}
...
{"type":"run_end","status":"passed","summary":"...","duration":45.2,...}

Event Schema

Step Events

Type	Key Fields	Description
`step_start`	`index`, `objective`, `child_id`*	Step began
`step_event`	`index`, `event`*, `detail`, `success`	Activity within a step
`step_end`	`index`, `status` (passed\|failed), `duration`, `summary`	Step completed

*optional
**event values: screenshot, reasoning, action, vision, assertion, evaluation

Flow Events

Type	Key Fields	Description
`run_start`	`objective`, `timestamp`	Run started
`bifurcation`	`flows[]`, `count`	Agent branched into sub-flows
`child_agent_start`	`child_id`, `objective`, `parent_step`	Child agent spawned
`child_agent_end`	`child_id`, `success`, `steps_taken`, `summary`	Child agent finished
`ask_user`	`question`, `step_index`, `options`*	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 progress event (for example `code: "unresolved_variables"`)
`error`	`message`	Error occurred
`run_end`	(see below)	Final event of a one-shot `run`: 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 one-shot run. It contains the complete test result. Always check the process exit code too: an early refusal can exit without a run_end event.

{
  "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,
  "final_state": {
    "price": "$29.99",
    "product_name": "Wireless Headphones"
  },
  "context": {
    "memory": {},
    "variables": {},
    "pointer": "(passed) Searched for laptop on Amazon"
  },
  "token_usage": {
    "reasoning_input": 12000,
    "reasoning_output": 800,
    "vision_input": 5000,
    "vision_output": 200
  },
  "session_dir": "~/.testmuai/kaneai/sessions/2026-04-14_10-30-45_a1b2c3",
  "run_dir": "~/.testmuai/kaneai/sessions/2026-04-14_10-30-45_a1b2c3/runs/0",
  "test_url": "https://test-manager.lambdatest.com/projects/123/test-cases/456"
}

Key Fields

Field	Description
`status`	`"passed"` or `"failed"`
`summary`	Full description of what the agent did
`one_liner`	Short single-sentence summary
`reason`	Why the run stopped (present on failure)
`final_state`	Values extracted via “store as” objectives
`test_url`	Link to the dashboard for this run
`session_dir`	Path to session-level logs
`run_dir`	Path to run-level logs, step JSON, screenshots
`token_usage`	Token consumption breakdown
`condition_results`	`--analyzer-only` runs only: `boolean[]`, one verdict per `--condition`, in order. See Assertion controls and current-page analysis

The .evidence proof pack

Every Kane CLI run produces an .evidence pack stored natively in the results folder, so failure context travels with the run instead of living in a separate dashboard. Each pack contains the full execution proof for the run: step-by-step traces, screenshots, video, and command, network and console logs, plus the NDJSON event stream and result codes. Coding agents and humans read the same evidence to see exactly what happened, where it failed, and why.

Parsing Output

Get the run_end event:

# Get just the final result
kane-cli run "..." --agent 2>/dev/null | tail -1 | jq .

# Extract status
kane-cli run "..." --agent 2>/dev/null | tail -1 | jq -r '.status'

# Extract a stored value
kane-cli run "go to example.com, store the price as 'price'" --agent 2>/dev/null \
  | tail -1 | jq -r '.final_state.price'

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	Logs only	Logs + progress UI
Use case	AI agents, programmatic tools	Human development

Next Steps

Error Codes: Complete reference of result_code values and recommended actions
Parallel Execution: Run multiple tests concurrently
Skills: Install the Kane CLI skill for Claude, Codex, or Gemini
CLI Reference: Full flag and command reference

​Enable Agent Mode

​Output Format

​Event Schema

​Step Events

​Flow Events

​Unresolved-Variable Warning

​The run_end Event

​Key Fields

​The .evidence proof pack

​Parsing Output

​Command-Specific Completion

​Handling ask_user Events

​Agent Mode vs Interactive Mode

​Next Steps

Enable Agent Mode

Output Format

Event Schema

Step Events

Flow Events

Unresolved-Variable Warning

The `run_end` Event

Key Fields

The .evidence proof pack

Parsing Output

Command-Specific Completion

Handling `ask_user` Events

Agent Mode vs Interactive Mode

Next Steps