Kane CLI Command & Flag Reference

Commands

`kane-cli --tui`

Launch the interactive TUI.

kane-cli --tui

`kane-cli run`

Run a browser automation test.

kane-cli run "<objective>" [options]

Flag	Description	Default
`--url <url>`	Start URL for the run. Overrides the configured `default_url`; bare domains are normalized to `https://`	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
`--headless`	Run Chrome without a visible window	Off
`--max-steps <n>`	Maximum agent reasoning steps	`50`
`--timeout <s>`	Abort after N seconds	No limit
`--cdp-endpoint <url>`	Connect to an existing Chrome via CDP	Auto-launch Chrome
`--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, use `testrun run --remote`	Local Chrome
`--variables <json>`	Inline variable JSON	None
`--variables-file <path>`	Load variables from a JSON file	None
`--global-context <file>`	Override global context markdown	`~/.testmuai/kaneai/global-memory.md`
`--local-context <file>`	Override local context markdown	`.testmuai/context.md`
`--session-context <json>`	JSON context from earlier runs, loaded for the agent	None
`--agent`	Output structured NDJSON (for AI coding agents)	Off
`--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`	Config value, otherwise `off`
`--assertion-mode <mode>`	`dom` (DOM-based extraction and assertions, vision fallback) or `visual` (vision model only). Overrides `config set-assertion-mode`	`dom`
`--final-validation <on\|off>`	Append the synthesized `cp_final` checkpoint that verifies the objective as a whole. Overrides `config set-final-validation`	Off
`--analyzer-only`	Judge each `--condition` against the current desktop browser page and report verdicts in `condition_results` on `run_end`. No objective, no actions, nothing saved. Use `--agent` or non-TTY input	Off
`--condition <text>`	A condition to judge under `--analyzer-only`. Repeatable; order is preserved in `condition_results`	None
`--network-ws`	Capture WebSocket frames for assertions and extraction (experimental, `run` only)	Off
`--network-sse`	Capture Server-Sent Events messages for assertions and extraction (experimental, Chromium-only, `run` only)	Off
`--code-export`	Generate code export after run uploads	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
`--username <user>`	Basic auth username (overrides stored profile)	N/A
`--access-key <key>`	Basic auth access key (overrides stored profile)	N/A

If a {{name}} in the objective 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. The warning does not change the exit code. See Unresolved variables. Mobile run flags. The emulator and simulator targets need macOS Apple Silicon. The android and ios targets run on a real device in the cloud, from any machine. A real device comes from the device hub, the cloud service that hands out real devices to test sessions.

Flag	Description	Default
`--target <name>`	Which target to run against: `desktop`, `emulator`, `simulator`, `android`, or `ios`	Saved session target, otherwise `desktop`
`--device-name <name>`	The device, named as `kane-cli devices list` prints it. On an emulator or simulator, also pass `--os-version`. On a real device, either one alone is enough, and a name can be a pattern such as `Pixel.*`. With neither, the hub picks a device	Config value. When unset, a TTY run opens a one-time picker and saves the choice. Non-interactive runs require a device
`--os-version <version>`	The device’s OS version, for example `14` or `17.5`. On its own, it matches any device on that version	Config value
`--app <path\|APPid>`	The app under test. A build (emulator `.apk`, simulator `.zip`, android `.apk` or `.aab`, ios `.ipa`) or an uploaded app id	Config value. Required for every mobile run
`--no-stream`	On a real device, don’t open the live view (a view-only picture of the device screen) for this run	At a terminal, the live view opens in its own window. It never opens for agents

On the desktop target, the device flags and --app are ignored. See Mobile Testing for setup.

`kane-cli doctor`

Check the mobile tooling this machine needs for one target, emulator or simulator, and install the tooling Kane CLI manages for it. --target is required.

kane-cli doctor --target emulator              # required checks, each with a fix if it fails
kane-cli doctor --target simulator --install   # install the test tooling Kane CLI manages

doctor prints one line per required check, each with a fix. Run kane-cli login before --install. See Mobile Testing.

`kane-cli devices list`

List the emulators, simulators, or real devices Kane CLI can run against. --target is required: emulator, simulator, android, or ios. android and ios list the real devices in the cloud and take --remote. To choose a device for a run, pass --device-name and --os-version exactly as the list prints them.

kane-cli devices list --target emulator             # the emulators on this machine
kane-cli devices list --target simulator --remote   # the simulators the cloud grid can provision
kane-cli devices list --target simulator --remote --os-version 17.5   # only that OS version
kane-cli devices list --target android --remote     # the real Android devices in the TestMu AI cloud

See Remote Runs for the grid catalog.

`kane-cli apps list`

List the uploaded builds your account can use for a target: emulator, simulator, android, or ios (android and ios list real-device builds). The APP ID column is what --app and kane-cli config set-app accept.

kane-cli apps list --target emulator
kane-cli apps list --target ios

`kane-cli testmd run`

Run a test from one _test.md file. For each step, Kane CLI either replays a cached recording or authors a fresh one.

kane-cli testmd run <path> [options]

testmd run accepts the shared run flags (--url, --allow-missing-url, --headless, --max-steps, --timeout, --cdp-endpoint, --ws-endpoint, the context and variable flags, --username / --access-key, --mode, --bug-detection, --assertion-mode, --final-validation, --agent, the code export flags, and the mobile flags). --network-ws, --network-sse, and --analyzer-only work only with run. These flags are available only on testmd run:

Flag	Description	Default
`--name <name>`	Persist a session name. Must match `[a-zA-Z0-9_-]+`	None
`--on-lock-conflict <mode>`	Policy when another user holds the lock: `readonly`, `fail`, or `wait`	None
`--push`	Always commit at the end of the run	Off
`--no-adaptive-heal`	Turn off adaptive healing after a replay failure	Healing enabled
`--author`	Re-author all authorable steps in place, keeping the test’s existing identity, and commit a new version. Steps marked replay-only still replay	Off

Adaptive healing is on by default. After a replay failure, the runner tries up to three smaller and smaller replay windows, then fully re-authors the authorable steps. The --retry and --retry-count flags are accepted but have no effect: they only print a notice. Adaptive healing handles failed replays. Before any step runs, kane-cli checks every {{name}} used by the authored steps. A name with no value prints a warning and the run continues. Replayed steps are not checked. Under --agent, wait for both the test_md_done event and the process exit. kane-cli testmd export <path> regenerates the code export from existing recordings and takes --language (python or javascript), not --code-language. See Running test.md files for the full flag reference and the other testmd subcommands (list, status, delete, export, sync).

`kane-cli testrun run`

Run many authored _test.md files as one execution: one summary, one exit code, and one sealed evidence pack for the whole suite.

kane-cli testrun run                                              # every *_test.md under the cwd
kane-cli testrun run tests/checkout_test.md tests/login_test.md   # explicit paths
kane-cli testrun run --match 'tests/e2e/.*' --tags smoke          # select by project-relative path and tags

Each path you pass must be a _test.md file. To select a directory of tests, use --match on the project-relative path instead of passing the directory.

Flag	Description	Default
`--match <regex>`	Keep tests whose project-relative path matches the regex. The path uses your operating system’s separators: `tests/app/` on macOS and Linux, `tests\app\` on Windows. In cmd.exe, wrap the regex in double quotes, because single quotes are treated as literal characters	None
`--tags <list>`	Keep tests whose frontmatter tags match any listed tag (repeatable or comma-separated)	None
`--parallel <n>`	Worker count	`1`
`--on-failure <mode>`	`continue` or `fail-fast`	`continue`
`--name <label>`	Run title	Derived from the selection
`--dry-run`	Build and validate the plan only; run nothing	Off
`--agent`	Print NDJSON on stdout even in a terminal. This is the same stream you get when stdin is not a TTY	Off
`--no-adaptive-heal`	Turn off adaptive healing after a replay failure	Healing enabled
`--bug-detection <mode>`	`off`, `stop`, or `continue`. See Configuration	Config value
`--headless`	Run Chrome without a visible window	Off
`--remote [backend]`	Dispatch the suite to the cloud grid instead of local Chrome or local devices (default backend: `hyper`). Needs `kane-cli plugin install remote-execution`. See Remote Runs	Off
`--device-name <name>`	Device for the suite’s mobile members: as `kane-cli devices list` prints it locally, or a grid catalog device with `--remote`	Member’s `device_name:`
`--os-version <version>`	OS version for the mobile members (`14`, `17.5`). On its own, it matches any device on that version	Member’s `os_version:`
`--username <user>` / `--access-key <key>`	Basic auth instead of OAuth	None

Adaptive healing is on by default; --no-adaptive-heal turns it off. The --retry and --retry-count flags are accepted but have no effect: they only print a notice. A local suite that contains an emulator or simulator member must use --parallel 1. Real-device members can run in parallel, up to the real devices your plan allows. testrun run has no --variables flag. To supply values, fill the shared variables file or the member’s own variables: frontmatter. A member that uses a {{name}} with no value still passes preflight, with a warning. See Batch runs (testrun).

`kane-cli maintain evolve`

Re-design the parent use-case of a test, scenario, acceptance criterion, or use-case. Before anything runs, kane-cli always states the blast radius: the scenario and test pairs it will re-design.

kane-cli maintain evolve <ref> [--because "<reason>"]                 # any designed entity → its parent use-case
kane-cli maintain evolve --from-stale                                 # every use-case with stale designed entities
kane-cli maintain evolve <ref> --mode agent                           # headless: the blast-radius question pauses the run
kane-cli maintain evolve <ref> --mode agent --answer evolve:<use-case>=1   # 1 = proceed, 2 = decline

Flag	Description
`--from-stale`	Evolve every use-case with stale designed entities
`--because <reason>`	Re-design a target even if it is not stale. The reason is recorded as the context for the change
`--mode <mode>`	`interactive` or `agent`; any other value is refused with `MODE_USAGE`. In `agent` mode, kane-cli prints NDJSON on stdout, the blast-radius confirmation becomes a question, and the run pauses with exit `3`
`--answer <pairs...>`	With `--mode agent`: answer a paused run’s question by its id, `evolve:<use-case>=1` (proceed) or `=2` (decline). Repeatable. An answer to a question the run does not ask is refused with `ANSWER_USAGE`

See Maintaining the suite and Assurance automation for the event stream.

`kane-cli plugin`

Manage the plugins Kane CLI installs under ~/.testmuai/kaneai/plugins/. The one you are most likely to need is remote-execution, which owns the HyperExecute binary behind kane-cli testrun run --remote.

kane-cli plugin install remote-execution      # install (add --version <v> to pin one)
kane-cli plugin list                          # what is installed, with versions
kane-cli plugin doctor remote-execution       # readiness: installed, binary present, logged in
kane-cli plugin remove remote-execution

Authenticate with . Opens a browser for OAuth, or accepts credentials for basic auth.

# OAuth (interactive)
kane-cli login [--profile <name>]

# Basic auth (non-interactive)
kane-cli login --username <user> --access-key <key> [--profile <name>]

See Authentication for details on profiles and auth methods.

`kane-cli logout`

Revoke tokens and remove stored credentials for the active profile.

kane-cli logout

`kane-cli whoami`

Show the active profile and authentication status.

kane-cli whoami [--profile <name>]

Prints profile, environment, auth method, username, and token state (for OAuth).

`kane-cli balance`

Show credit balance for the active profile.

kane-cli balance [--profile <name>]

`kane-cli profiles`

Manage named authentication profiles.

kane-cli profiles list           # List all profiles
kane-cli profiles switch <name>  # Switch the active profile
kane-cli profiles delete <name>  # Delete a profile

See Authentication: Profiles for details.

`kane-cli config`

View and modify persistent settings.

kane-cli config show                       # Show all settings
kane-cli config set-window <W>x<H>        # Set browser window size
kane-cli config set-mode <action|testing>  # Set run mode
kane-cli config chrome-profile [path]      # Set Chrome profile (interactive picker if no path)
kane-cli config project [id]               # Set Test Manager project (interactive picker if no id)
kane-cli config folder [id]                # Set Test Manager folder (interactive picker if no id)
kane-cli config set-target <target>        # Set run target: desktop | emulator | simulator | android | ios
kane-cli config set-device-name <name>     # Set default mobile device, as kane-cli devices list prints it
kane-cli config set-os-version <version>   # Set the default mobile device's OS version
kane-cli config set-app <path|APPid>       # Set default app under test for mobile runs
kane-cli config set-url <url>              # Set the default start URL (bare domains are normalized to https://)
kane-cli config reset-url                  # Clear the saved default start URL
kane-cli config set-device-stream <on|off>           # Real-device live view (default on)
kane-cli config set-auto-grant-permissions <on|off>  # Auto-grant app permissions on Android, for the saved target (default on)
kane-cli config set-auto-accept-alerts <on|off>      # Auto-accept system alerts on iOS, for the saved target (default on)
kane-cli config set-bug-detection <off|stop|continue>  # Set bug detection while authoring
kane-cli config set-assertion-mode <dom|visual>        # Set assertion mode (default dom, with vision fallback)
kane-cli config set-final-validation <on|off>          # Set the synthesized cp_final checkpoint (default off)
kane-cli config set-network-ws <on|off>                # Experimental WebSocket capture (default off)
kane-cli config set-network-sse <on|off>               # Experimental SSE capture, Chromium-only (default off)

Commands without arguments (chrome-profile, project, folder) launch an interactive picker UI. AI agents cannot run these: ask the user to run them directly.

See Configuration for the full settings reference.

`kane-cli feedback`

Submit feedback on a completed test run.

kane-cli feedback \
  --test-id <id> \
  --feedback-type <positive|negative> \
  --details "optional message"

Exit Codes

`kane-cli run`

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`

Under --analyzer-only, exit 0 means all conditions were judged, not that all are true. Exit 1 means a result was missing, and 3 means cancelled. An unresolved-variable warning does not change the exit code.

`kane-cli testmd run`

Code	Meaning
`0`	Run passed (or the file had no steps)
`1`	At least one non-optional step failed
`2`	Error before or during the run: parse error, auth error, organisation mismatch, Chrome launch failure, invalid flag, lock conflict with `--on-lock-conflict fail`
`3`	Cancelled (Ctrl+C confirmed) or timed out (including `--on-lock-conflict wait` timing out)

`kane-cli testrun run`

Code	Meaning
`0`	All members passed
`1`	At least one member failed or broke
`2`	Usage error, invalid plan (preflight failures), or auth error. Nothing ran
`3`	Cancelled (Ctrl-C)

With --dry-run, exit 0 means the plan is valid and exit 2 means the plan was refused.

`kane-cli maintain evolve --mode agent`

The final done event carries the status: complete (exit 0), refused (exit 2: a usage error, MODE_USAGE, ANSWER_USAGE, or an explicit target that was never designed), paused (exit 3: evolve is waiting on its question or on the design session), or error with the design run’s own code. For generate and the assurance commands, see Generate workflow and Assurance automation. Always check the process exit code: an early refusal, an invalid plan, or a dry run can exit without the normal completion event.

TUI Slash Commands

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

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 input history
Tab	Accept autocomplete

Settings Reference

Setting	Default	Command
`window_size`	`1920x1080`	`config set-window`
`default_url`	`https://kaneai-playground.lambdatest.io` (treated as unset)	`config set-url`
`target`	`desktop`	`config set-target`
`device_name` / `os_version`	None	`config set-device-name` / `config set-os-version`
`app`	None	`config set-app`
`bug_detection`	`off`	`config set-bug-detection` or `--bug-detection` flag
`model`	`v16-alpha`	Internal default
`mode`	`testing`	`config set-mode`
`chrome_profile_path`	Empty (temporary per run)	`config chrome-profile`
`project_id` / `project_name`	None	`config project`
`folder_id` / `folder_name`	None	`config folder`
`code_export.enabled`	`true`	TUI menu or `--code-export` flag
`code_export.language`	`python` (or `javascript`)	`--code-language` flag
`code_export.skip_validation`	`true`	TUI menu or `--skip-code-validation` flag

Settings are stored at ~/.testmuai/kaneai/tui-config.json. See Configuration for details.

Directory Structure

~/.testmuai/kaneai/
├── tui-config.json              # Persistent settings
├── global-memory.md             # Global agent context
├── chrome-profiles/             # Named Chrome user profiles
│   └── <name>/
├── profiles/                    # Stored credentials
│   └── <profile>/
│       └── <environment>/
│           └── credentials      # OAuth tokens or basic auth (mode 0600)
├── sessions/                    # All session history
│   └── <session-id>/
│       ├── session.json         # Session metadata and run list
│       ├── tui.log              # Session event log
│       ├── runs/
│       │   └── <n>/             # Per-run directory
│       │       └── run-test/
│       │           ├── actions.ndjson
│       │           └── screenshots/
│       └── code-export/         # Generated code (when enabled)
└── variables/                   # Global variable files
    └── *.json

.testmuai/                       # Project-local (in cwd)
├── context.md                   # Project-specific agent context
└── variables/
    └── *.json                   # Project-specific variables

​Commands

​kane-cli --tui

​kane-cli run

​kane-cli doctor

​kane-cli devices list

​kane-cli apps list

​kane-cli testmd run

​kane-cli testrun run

​kane-cli maintain evolve

​kane-cli plugin

​kane-cli login

​kane-cli logout

​kane-cli whoami

​kane-cli balance

​kane-cli profiles

​kane-cli config

​kane-cli feedback

​Exit Codes

​kane-cli run

​kane-cli testmd run

​kane-cli testrun run

​kane-cli maintain evolve --mode agent

​TUI Slash Commands

​Keyboard Shortcuts

​Settings Reference

​Directory Structure

Commands

`kane-cli --tui`

`kane-cli run`

`kane-cli doctor`

`kane-cli devices list`

`kane-cli apps list`

`kane-cli testmd run`

`kane-cli testrun run`

`kane-cli maintain evolve`

`kane-cli plugin`

`kane-cli login`

`kane-cli logout`

`kane-cli whoami`

`kane-cli balance`

`kane-cli profiles`

`kane-cli config`

`kane-cli feedback`

Exit Codes

`kane-cli run`

`kane-cli testmd run`

`kane-cli testrun run`

`kane-cli maintain evolve --mode agent`

TUI Slash Commands

Keyboard Shortcuts

Settings Reference

Directory Structure