Kane CLI Modes: TUI, Headless & Agent

Kane CLI has three modes. Choose based on who (or what) is running the test.

Mode	Command	Output	Best For
Interactive TUI	`kane-cli --tui`	Terminal UI	Development, exploration, chained sessions
Non-Interactive CLI Mode	`kane-cli run "..." --headless`	Formatted text + JSON	CI/CD, shell scripts
Agent Mode	`kane-cli run "..." --agent`	NDJSON on stdout	AI coding agents (Claude, Codex, Gemini)

Interactive TUI

Launch the TUI:

kane-cli --tui

The TUI is the right surface when you are exploring objectives, debugging failures, or working through a multi-run flow that should share browser state. On launch, Kane CLI runs a short boot sequence (auth check, environment resolution, mascot animation), then drops into the main menu. The top-level entries are:

Entry	Purpose
Run	Start a run or adjust per-run options
Auth	Login, logout, switch profile, view identity, check credit balance
Config	View and change settings (mode, project, folder, Chrome profile, window size)
Exit	Graceful shutdown (uploads the session if applicable)

Use the arrow keys to navigate, Enter to select, and Esc to back out of a submenu.

Chat Mode

Selecting Run > Start Run switches the TUI into chat mode. Type your objective at the prompt and press Enter. The agent begins streaming steps into the scrollback: each step shows the action taken, a short rationale, and a status icon. When the run finishes, a result summary block appears. Subsequent runs in the same TUI session reuse the same browser, so you can iterate on objectives without re-logging in or re-navigating.

Slash Commands

Typing / in chat mode opens an autocomplete palette. Continue typing to filter, use the arrow keys to select, and press Enter to insert the command.

Command	Args	Description
`/run`	`"objective"`	Execute a test run
`/login`	`[--profile name]`	OAuth login
`/logout`	`[--profile name]`	Logout and revoke tokens
`/whoami`	`[--profile name]`	Show profile info
`/balance`		Show credit balance
`/profiles`	`list\|switch\|delete`	Manage profiles
`/config`	`show\|set-window\|set-url\|set-mode\|chrome-profile\|project\|folder`	Manage configuration
`/mobile`		Switch the session to a device: an emulator, a simulator, or a real Android or iOS device
`/desktop`		Switch the session back to desktop (Chrome)
`/doctor`		Check mobile tooling and devices
`/new`		Start a fresh session (uploads the current session and seals its evidence pack first)
`/summary`	`[index]`	View detailed run summaries
`/cancel`		Abort the current run
`/help`		Show the command reference
`/clear`		Clear chat history
`/exit`		Quit Kane CLI

You can also send a bare line of text without a leading /. It is treated as the objective for /run.

History Search

Press Ctrl+R in the input prompt to open reverse history search across past inputs in this and previous sessions. Type to filter, use the arrow keys to move between matches, Enter to accept, and Esc to dismiss. The prompt also offers ghost-text completion: if your current input is a prefix of a recent entry or a slash command, the rest is shown dimmed and Tab accepts it.

Status Bar

A two-row status bar sits at the bottom of the TUI:

Indicator	Meaning
Model	The model in use (default `v16-alpha`)
Session	Last six characters of the current session ID
Auth dot	Green when authenticated, red when not logged in
Profile	Active profile name (or `no profile`)
Environment	`prod` (green) or a yellow `stage` warning
Runs	Number of runs completed in this session
Hint line	Context-aware shortcuts (chat: `ctrl+c cancel/exit`; menu: `↑↓ navigate ↵ select esc back`)

Multi-Run Sessions

Every run launched from the same TUI invocation shares one Chrome instance and one session directory. Cookies, login state, and tabs persist across runs, so an early run can log in and a later run can land mid-application without re-authenticating. Starting a fresh session from inside the TUI is done with /new, which uploads the current session and then resets state.

> go to https://myapp.com and log in as admin
  ✓ PASSED (5 steps, 8.2s)

> navigate to User Management and create a new user "testuser@example.com"
  ✓ PASSED (7 steps, 12.1s)

> verify the new user appears in the users table
  ✓ PASSED (3 steps, 4.5s)

Interactive Follow-Ups

If the agent needs information mid-run (for example, a one-time code or a clarifying choice), it pauses and asks at the input prompt. Type your answer and press Enter; the agent resumes from where it left off. Use Ctrl+C to cancel the run instead of answering.

Keyboard Shortcuts

Shortcut	Action
Enter	Submit objective
Ctrl+C	Cancel current run
Ctrl+C (twice)	Exit TUI
Ctrl+R	Reverse history search
Esc	Go back / close picker
Up / Down	Navigate menu or history
Tab	Accept autocomplete in chat mode

Cancelling and Exiting

Action	Shortcut
Cancel the current run	`/cancel`, or Ctrl+C once during a run
Exit the TUI	`/exit`, or Ctrl+C twice in quick succession
Force exit during shutdown upload	Ctrl+C twice while exit is in progress

A graceful /exit runs the upload pipeline (if applicable), seals the session’s evidence pack, offers to open it in the browser viewer, and prints any final links to your terminal scrollback before the process ends.

Non-Interactive CLI Mode

kane-cli run "Search for 'automation testing' on Google" \
  --url https://google.com \
  --headless

kane-cli run is the headless surface. It is the right choice for CI jobs, shell scripts, scripted invocations, and any environment that has no interactive TTY. Progress streams to stderr; the final JSON result is written to stdout.

Basic invocation

A minimal run:

kane-cli run "Search for 'noise-cancelling headphones' on amazon.com"

A longer invocation with options:

kane-cli run "Log in as {{tester}} and verify the dashboard loads" \
  --headless \
  --max-steps 40 \
  --timeout 300 \
  --variables-file ./vars.json

Run options

The customer-facing flags accepted by kane-cli run:

Flag	Description	Default
`--headless`	Run Chrome in headless mode.	Off
`--max-steps <n>`	Maximum agent steps.	`50`
`--timeout <seconds>`	Kill the run after N seconds.	None
`--url <url>`	Start URL for the run. Overrides the configured `default_url`; bare domains are normalized to `https://`. See Default start URL.	Config `default_url`
`--allow-missing-url`	Non-TTY only. If no start URL resolves, start from the browser’s current page instead of failing. A provided `--url` is still used.	Off
`--cdp-endpoint <url>`	Connect to an existing Chrome via CDP.	None
`--ws-endpoint <url>`	Connect to a Playwright WebSocket endpoint (e.g. `wss://`). The run still executes on this machine and drives that browser; to run a whole suite on the grid instead, see `testrun run --remote`.	None
`--global-context <file>`	Override the global context Markdown file.	`~/.testmuai/kaneai/global-memory.md`
`--local-context <file>`	Override the local context Markdown file.	`<cwd>/.testmuai/context.md`
`--variables <json>`	Inline variables JSON.	None
`--variables-file <path>`	Load variables from a JSON file.	None
`--session-context <json>`	JSON context from earlier runs, loaded for the agent.	None
`--username <user>`	Basic auth username, used instead of OAuth.	None
`--access-key <key>`	Basic auth access key, used instead of OAuth.	None
`--mode <name>`	Run mode: `action` (strict) or `testing` (lenient).	Config value, otherwise `testing`
`--bug-detection <mode>`	Detect product bugs while authoring: `off`, `stop` (halt the run on a confirmed bug), or `continue` (record it and keep going). Overrides `config set-bug-detection`. See Configuration.	Config value, otherwise `off`
`--agent`	Plain NDJSON output, no colors or UI.	Off
`--code-export`	Generate code export after upload.	config (`true` by default)
`--code-language <lang>`	Code export language: `python` or `javascript`.	`python`
`--skip-code-validation`	Skip the worker-side validation that runs after code is generated.	On
`--no-skip-code-validation`	Run the worker-side validation after code is generated.	Off

Assertion, final-validation, current-page analysis and network-capture flags are covered in Assertion controls and current-page analysis.

Unresolved variables

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. In a terminal, the warning looks like the example in Variables and context. With --agent, it 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 one of:

value_missing: the key exists in file, but has no value.
not_declared: the key is not in any file. suggested_file is where to add it.
not_a_dataset_column: a ${x} that does not match any column of the dataset row the run was given.

The warning does not change the exit code. Some names are never checked: explicit {{global.*}} references (resolved from Test Manager at run time), names that an earlier step stores, and the {{smart.*}}, {{environment.*}}, {{secrets.*}}, and {{totp.*}} namespaces. For variables and context file behavior, see Variables and context. For code export and the run mode toggle, see Configuration.

Mobile runs

By default, a run targets the desktop browser (Chrome), which is what every example above uses. From any machine, you can instead point a run at a real device in the cloud: android or ios. On macOS Apple Silicon, you can also use a virtual mobile device on your machine: an emulator (a virtual Android device) or a simulator (a virtual iOS device). Every mobile run needs an app under test. From any other machine, you can run a saved emulator or simulator suite on the cloud grid with testrun run --remote.

# desktop (default): nothing changes for web runs
kane-cli run "Search for 'noise-cancelling headphones' on amazon.com"

# emulator (Android): install an .apk build and run against it
kane-cli run "Add the first item to the cart" --target emulator --app ./builds/app-debug.apk

# simulator (iOS): install a .zip build and run against it
kane-cli run "Sign in and open the account tab" --target simulator --app ./builds/MyApp.zip

# real device (any machine): the device hub picks a free device unless you name one
kane-cli run "Sign in and open the account tab" --target ios --app ./builds/MyApp.ipa
kane-cli run "Add the first item to the cart" --target android --device-name "Pixel.*" --app ./builds/app-release.apk

The mobile run flags:

--target desktop|emulator|simulator|android|ios: which target to run against. Defaults to the saved session target, otherwise desktop.
--device-name <name> and --os-version <version>: choose a device, using the values exactly as kane-cli devices list --target emulator|simulator prints them.
- On an emulator or simulator, a name needs a version, and a version on its own matches any device on that version.
- On a real device, either one alone is enough, and a name can be a pattern such as Pixel.*. With neither, the device hub (the cloud service that hands out real devices) picks one. List real devices with kane-cli devices list --target android|ios --remote.
In the TUI or a terminal, leaving them out opens a one-time picker and saves your choice. In non-interactive runs, a device must already be set, either with the flags or with kane-cli config set-device-name / set-os-version. Otherwise, the run exits and tells you how to fix it.
--app <path|APPid>: the app under test, required for every mobile run. Pass a build (emulator: .apk, simulator: .zip, android: .apk or .aab, ios: .ipa) or an uploaded app id (APP followed by six or more digits). kane-cli apps list --target <kind> lists yours. On the desktop target, the device flags and --app are ignored.
--no-stream: on a real device, don’t open the live view for this run. The live view is a view-only picture of the device screen. At a terminal, it opens in its own Chrome window by default. It never opens for agents.

In the interactive TUI, the first run offers a chooser of the targets this machine can run. A machine that can’t run emulators or simulators sees Desktop / Android / iOS. You can switch targets with /mobile and /desktop until the first run starts. After that, use /new to start a fresh session before you switch. Run /doctor to check mobile tooling and devices. For setup (Xcode or Android Studio, kane-cli login, and kane-cli doctor --target emulator|simulator --install) and the app formats each target accepts, see Mobile testing.

Output Streams

Stream	Contents
stderr	Live progress (banner, step tree, result box, links, upload progress, feedback prompt)
stdout	The final JSON `run_end` payload, including the share URL when an upload succeeds

This separation lets you capture each independently:

kane-cli run "..." > result.json 2> progress.log

In CI, redirect stdout to a file your job can parse and let stderr stream to the build log so engineers can read the run in real time. When stdin is not a TTY, Kane CLI automatically switches to plain NDJSON mode (the same as --agent). Each line on stdout is one JSON event terminated by a newline.

Exit Codes

Exit Code	Meaning
`0`	Run passed
`1`	Run failed (agent reached an unrecoverable failure, or the upload failed)
`2`	Error (auth, TMS credential exchange, configuration, Chrome, unknown subcommand, or unhandled exception)
`3`	Run was cancelled or hit the `--timeout`

Use these codes to gate downstream CI steps.

What You See at the End of a Run

When a run finishes, Kane CLI prints a result summary:

Field	Meaning
Status	`PASSED` (green check) or `FAILED` (red cross)
Steps	Total step count, with a `(N passed, M failed)` breakdown when there were failures
Duration	Wall-clock time in seconds (or minutes and seconds for longer runs)
Credits	Credits consumed, when reported
Summary	Bullet-point summary of what the agent did
Reason	Failure reason (failed runs only)

Below the summary, Kane CLI prints any of the following links:

Label	Points to
`ShareLink`	A shareable session URL on Test Manager
`TestCase`	The test case detail page in Test Manager
`CodeExport`	The local directory containing generated code (when code export is enabled)

Modern terminals render these as clickable hyperlinks. For details on what each link leads to, see Test Manager integration. The run is also captured as a sealed evidence pack: screenshots, per-step console/network logs, and failure records. In a terminal, Kane CLI offers to open it in the browser viewer; in agent or non-interactive runs it prints a one-line evidence: view locally with … hint to stderr instead.

Assertion controls and current-page analysis

run and testmd run support two assertion controls:

--assertion-mode dom|visual: dom (the default) checks the page’s DOM and falls back to vision when needed; visual uses the vision model only. To save a default, use config set-assertion-mode.
--final-validation on|off (default off): adds a generated cp_final checkpoint that verifies the objective as a whole. To save a default, use config set-final-validation. This setting works the same way in action and testing mode. Keep explicit final assertions in your objectives either way.

run --analyzer-only --condition "<condition>" checks the current desktop browser page against one or more conditions, without an objective, action steps, or a saved test. Repeat --condition to check several conditions. Use --agent or non-TTY input. Results are returned in condition_results: boolean[]. Exit 0 means all conditions were judged, not that all are true. Exit 1 means a result was missing, and 3 means cancelled. This mode rejects the mobile target, app, and device options, and the code-export and name options. The experimental run --network-ws and run --network-sse flags capture WebSocket and Server-Sent Events traffic. Both are off by default. To save a default, use config set-network-ws on|off and config set-network-sse on|off. SSE capture works in Chromium only. These flags work only with run, so do not add them to testmd or testrun commands. Code export is on by default, unless your saved configuration turns it off. It supports python (default) or javascript. run and testmd run use --code-language, while testmd export uses --language. Whether a run uploads does not depend on action or testing mode.

Feedback Prompt

After the result and links print, Kane CLI prompts you to rate the session with thumbs up or thumbs down. Use the left and right arrow keys to choose, Enter to submit, or Esc to skip. The rating is sent to Test Manager for the active test case; see Test Manager Integration for what is recorded.

Agent Mode

Add --agent to get structured NDJSON output designed for AI coding agents:

kane-cli run "Verify login page loads" --url https://myapp.com --agent --headless

With --agent:

The interactive TUI is fully suppressed: no boot screen, no menus
Each event is a single JSON line on stdout
Progress UI renders to stderr (clean separation)
Stdin is not used (no interactive prompts)

This mode is how Claude Code, Codex CLI, and Gemini CLI consume Kane CLI results. The agent reads the NDJSON stream, parses the final run_end event, and presents results to you. The run_end strategy applies to one-shot run only; testmd run, testrun run, generate and the assurance commands end in their own completion events. See Command-specific completion. See Agent Mode for the full event schema and parsing guide.

Always combine --agent with --headless in non-interactive environments to prevent display server errors.

​Interactive TUI

​Boot and Menu

​Chat Mode

​Slash Commands

​History Search

​Status Bar

​Multi-Run Sessions

​Interactive Follow-Ups

​Keyboard Shortcuts

​Cancelling and Exiting

​Non-Interactive CLI Mode

​Basic invocation

​Run options

​Unresolved variables

​Mobile runs

​Output Streams

​Exit Codes

​What You See at the End of a Run

​Assertion controls and current-page analysis

​Feedback Prompt

​Agent Mode

Interactive TUI

Boot and Menu

Chat Mode

Slash Commands

History Search

Status Bar

Multi-Run Sessions

Interactive Follow-Ups

Keyboard Shortcuts

Cancelling and Exiting

Non-Interactive CLI Mode

Basic invocation

Run options

Unresolved variables

Mobile runs

Output Streams

Exit Codes

What You See at the End of a Run

Assertion controls and current-page analysis

Feedback Prompt

Agent Mode