Modes of Operation

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.

Boot and Menu

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 an emulator or simulator
/desktop		Switch the session back to desktop (Chrome)
/doctor		Check mobile tooling and devices
/new		Start a fresh session (uploads the current session 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

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) 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

This mode is best for shell scripts, CI/CD pipelines, and any scenario where the interactive TUI is not needed.

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.	30
--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: proceed from the browser's current page instead of failing when no start URL resolves (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. TestmuAI wss://).	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>	Prior runs context JSON.	None
--username <user>	Basic auth username (skip OAuth).	None
--access-key <key>	Basic auth access key (skip 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.	Off
--code-language <lang>	Code export language (currently python).	python
--skip-code-validation	Skip post-codegen worker-side validation.	On
--no-skip-code-validation	Force post-codegen worker-side validation.	Off

Unresolved variables

Every {{name}} in the objective must have a value before the run starts. A name with no value stops the run there, with no browser and no session, exit code 2, and a receipt naming each variable and what it needs. There is no flag to bypass it: fill the value or remove the reference. With --agent, the refusal is a single typed event:

{"type":"error","code":"unresolved_variables","message":"2 variable(s) have no value — nothing was dispatched","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 (the key exists in file, with no value) or not_declared (the key is in no file, and suggested_file is where to add it). Names an earlier step stores, and the {{smart.*}}, {{environment.*}}, {{secrets.*}} and {{totp.*}} namespaces, are never checked.

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), so every example above is unchanged. On macOS Apple Silicon you can instead point a run at a virtual mobile device on this 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, run a saved mobile suite on the cloud grid with testrun run --remote.

Verified

# 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

The mobile run flags:

• --target desktop|emulator|simulator: which target to run against. Defaults to the saved session target, otherwise desktop.
• --device-name <name> and --os-version <version>: pick a device as kane-cli devices list --target emulator|simulator prints it. A name needs a version, and a version on its own matches any device running it. In the TUI or an interactive terminal, omitting them opens a one-time picker and the choice is saved. In non-interactive runs a device must already be set, with the flags or with kane-cli config set-device-name and kane-cli config set-os-version, or the run exits with the fix spelled out.
• --app <path|APPid>: the app under test, required for every mobile run. Pass a build (emulator: .apk, simulator: .zip) or an uploaded app id (APP followed by six or more digits), and kane-cli apps list --target <kind> lists yours. On the desktop target, the device flags and --app are ignored.

In the interactive TUI, a first run offers a Desktop / Emulator / Simulator chooser, and you can switch targets at any time with /mobile and /desktop. 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.

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	Test passed
1	Test failed (assertion not met)
2	Error (auth failure, Chrome crash)
3	Timeout or cancelled

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 TestMu AI Test Manager
TestCase	The test case detail page in TestMu AI Test Manager
CodeExport	The local directory containing generated code (when code export is enabled)

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. See Test Manager Integration for details.

---

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.

See Agent Mode for the full event schema and parsing guide.

tip

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