Kane CLI Browser Testing

Kane CLI — Browser Automation Skill

Use kane-cli for any task that requires a real browser: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use --agent for run and testmd run. testrun run emits NDJSON when stdin is not a TTY (0.8.21+ also takes --agent, which selects the same stream), so every testrun run line you write ends in < /dev/null (bash and zsh: macOS, Linux, Git Bash; in cmd.exe write < NUL; from PowerShell run it through cmd: cmd /c "kane-cli testrun run … < NUL"). Check the first stdout line: on 0.8.17+ it is {"type":"stream_start"…}. A prose plan there instead means the CLI is in terminal mode: it shows the human view and, after a real run, opens an evidence table that waits until q or Esc, so the process never exits on its own; stop it and rerun with the redirect. An empty stdout with a message on stderr is a usage error: read it. Assurance conversational commands use --mode agent.

Authoring test cases or scenarios? Never write them by hand: every test case comes from the assurance commands — Read references/assurance.md first.

• The user has requirement documents (a PRD, a spec, acceptance notes) → ingest them, then design.
• The user only describes what to test, in chat → write their description, in their words, to a requirements file, ingest that file, then design (§6). The description is the requirement.

Don't draft test cases in chat or scratch files: design produces structured, refinable, runnable _test.md output.

1. Every session: ready check, launch, result card. READ THIS FIRST

A one-line "Test passed" instead of the result card is a bug. A run that starts with no ready check is a bug too. This section is first so you don't miss it. Follow it exactly.

The order never changes: ready check → launch line → the run → result card. On a person's first session two things are added: a short tour sent with the launch line, and three choices asked after the first result. Nothing is asked before the first result.

1.1 Start with the ready check

Before the first kane-cli command of a session, run the preflight script that ships with this skill and show the ready card. It is one short command and takes about two seconds:

sh "<skill dir>/scripts/preflight.sh"

<skill dir> is the folder that holds this SKILL.md. Read references/ready-check.md for the card (a full table on the first session, one line afterwards), the problems that stop a run, and the sign-in flow. Two rules matter enough to repeat here: you start sign-in yourself with kane-cli login --oauth, and you never ask for an access key or password in chat.

If the preflight shows no saved preferences (its ## agent-config section is none, or has no onboarding.completed_at), this is the person's first session: Read references/first-run.md before you launch.

1.2 How to launch kane-cli

All platforms use your shell tool (Bash) to launch kane-cli. Do NOT use Monitor: it creates excessive noise.

Tag every command with your runtime. Put KANE_CLI_USER_AGENT=<your-runtime> in front of every kane-cli command you run. Pick a short, stable identifier for the AI assistant or IDE running this skill (e.g. claude-code, codex, gemini, cursor, kiro, aider) and use the same value for the whole session. Do it inline on each command: an export does not survive from one shell call to the next in most agent hosts. Do not show the prefix in commands you quote to the person.

KANE_CLI_USER_AGENT=<your-runtime> kane-cli run "<objective>" --agent <other-flags>

On Windows PowerShell: $env:KANE_CLI_USER_AGENT='<your-runtime>'; kane-cli run "<objective>" --agent <other-flags>.

Watch mode. Use the person's saved preference (references/agent-config.md). With none saved, show the browser unless the preflight says there is no display, an SSH session, or CI: then add --headless.

Keeping runs. When the person's saved purpose is suite or ask, add --name <short-slug> to every one-off run. A named run is recorded as a _test.md while it runs, so keeping it afterwards costs nothing, and a run launched without a name cannot be kept without running again. With one-off, leave the flag out. Details: references/first-run.md §4.

Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the result card. Wait for process completion on testmd run too, but parse its own completion event, test_md_done. An intermediate run_end does not finish a saved test.

Set a generous timeout (up to 600000ms) since browser runs can take a while.

1.3 Before you launch

In one message, before invoking Bash, send the ready card and then:

Starting browser task: <one-line restatement of the user's objective>.

That line tells the user something is in progress. No todos needed: Bash returns all output at once and you summarize it below. On a first session, the tour from references/first-run.md goes in this same message, right after the launch line, so the person reads it while the run works.

1.4 After the run: summarize what happened

Once Bash returns, parse the captured NDJSON stdout and present a concise summary of what happened. Not every event deserves a line. Surface what matters and skip the noise. (Skip the summary entirely when the person's preference is results-only.)

Progress events have step/status/remark fields and no type field.

What to surface

What to skip

• Individual passing steps: fold them into the overall progress line
• Internal field names (step, status, remark, run_end, final_state, bifurcation, session_dir, stream_start, project_folder_auto_defaulted, etc.): translate to plain language. A project_folder_auto_defaulted event fires before progress when the run-startup gate auto-resolves a project/folder; surface it as one line ("kane-cli auto-selected project X / folder Y for this run") and move on. Details: references/test-manager.md.

For short runs (≤ 3 steps), you may list each step individually since there's nothing to fold.

1.5 The result card

The terminal event has type: "run_end" and stable fields: status, summary, one_liner, duration, credits_consumed, final_state, test_url, session_dir, run_dir.

For a passing run, always emit this exact table (substituting the field values):

| | |
|-------|-------|
| 🟢 **Result** | Passed |
| 🎯 **Task** | <one_liner> |
| ⏱️ **Duration** | <duration, as 1m 54s> |
| 👣 **Steps taken** | <count of completed progress events (done/failed), retaining child/execution context> |
| 💳 **Credits** | <credits_consumed, rounded> used · about <ready check balance minus used> left |
| 📝 **What happened** | <summary> |
| 📁 **Evidence** | Want to open the run evidence in your browser? |
| 🔗 **Test case** | [Open in Test Manager](<test_url>) |
| ➡️ **Next** | <two things you can do right now, e.g. add a payment step · run it headless in CI> |

If final_state has values (the user used "store as X", see §4), append a second table:

| 📦 What was found | Value |
|-------------|----------------|
| <key from final_state, humanized> | <value> |

If the objective used assertions ("assert …", "verify …"), append a pass/fail table per assertion derived from the run summary and step remarks.

Every other result has its own card in references/cards.md: a run that didn't start, one that stopped early, a possible product bug, a saved test, and a suite (local or cloud grid). Read it before presenting any of those. The rules there apply to every card: one short sentence per cell, failures first, ➡️ Next is an offer you can act on, and secret-looking values never go in chat.

1.6 On failure

For exit code 1 (or status: "failed" in run_end), present the failure card. Never show raw paths or NDJSON.

| | |
|-------|-------|
| 🔴 **Result** | Failed at step <n> of <total> |
| 🎯 **Task** | <one_liner, or the objective in a few words> |
| ⏱️ **Duration** | <duration, as 1m 12s> |
| 💳 **Credits** | <credits_consumed, rounded> used |
| 📝 **What happened** | <plain-language description of the failing step's remark> |
| 🔍 **Likely cause** | <your diagnosis: missing element, slow page, ambiguous objective, auth wall, etc.> |
| 📁 **Evidence** | Want to open the run evidence in your browser? |
| ➡️ **Next** | <a retry you can run now> · <walk through the failing step> |

The failing step's screenshot lives inside the run's evidence pack (the stderr hint names the pack path): extract it with unzip <pack> "tests/*/steps/*/screenshot.png" -d <tmpdir>, Read it, and show it under the card. For the pack layout and deeper diagnosis, see references/debug.md.

Exit code 2 means nothing ran: that is a 🟡 Didn't start card, not a failure (references/cards.md §4).

1.7 After the first result: three choices, then save

On a first session only, right after the first result card, save the defaults this run used, then ask the three choices from references/first-run.md §4 (watch mode, where results go, one-off or saved suite) as the last thing in your turn, and save the answers when they arrive. Some hosts hand control back before the person answers: end your turn there and save on their reply. On every later session none of this is asked again.

The live status strip (Claude Code only) has its own once-only question. Onboarding is shared by every agent the person uses, but the strip exists only in Claude Code, so the person may have finished their first session in another agent without ever being asked. In Claude Code, in any session: if the preflight's ## agent-config has no strip.claude-code.offered_at, kane-cli is 0.8.17 or newer, and node= is not empty, ask the strip question once, after that session's first result card, as the last thing in your turn. On a first session it simply rides along as the fourth choice. It is recommended, never turned on without a yes, and you record offered_at either way so it is never asked twice. Read references/live-strip.md §3 for the wording.

2. Decision tree

When the user's request involves a browser — or writing test cases:

Is kane-cli installed, signed in and ready?

• Unknown → run the preflight and show the ready card (§1.1, references/ready-check.md)
• A problem that stops the run → offer the fix from the card; deeper setup lives in references/setup-and-config.md
• Ready ↓

What does the user want?

• A single one-shot browser task → build a kane-cli run --agent command (§3 + §4)
• A test they want to save / re-run / commit → Read references/testmd.md first, then use kane-cli testmd
• Run a suite of saved tests (several _test.md at once) → Read references/testrun.md first, then use kane-cli testrun run … < /dev/null
• Need test cases from a description the user gives in chat, with no document → don't hand-write them; write the description to a requirements file and design from it (§6)
• Has requirement documents (PRD/spec) and wants a designed suite, coverage accounting, or suite upkeep → Read references/assurance.md first — the assurance commands (context/design/cover/maintain reconcile, kane-cli 0.6.1+; several features need newer releases, up to 0.8.14+ — the reference marks each)
• A designed test (its _test.md carries an assurance: block) failed a run → Read references/assurance.md §6.1 before touching the file — an edit is adopted as the next design version on the next run; classify the failure first (app bug → report it; requirement changed → reconcile; wording → redesign through the CLI; capability missing → stop), and edit a step of an existing designed test by hand only after reading references/objectives-cookbook.md
• Share the context store with a team, join a teammate's, keep two stores level, or resolve a sync conflict → Read references/context-sync.md first — kane-cli context sync, kane-cli context push, kane-cli context pull and kane-cli context clone (kane-cli 0.8.14+); the store is shared through a location, never by copying or git-merging .context/
• Multiple independent browser tasks → Read references/parallel.md first
• View, share, or validate run evidence (.evidence packs) → Read references/evidence.md
• Debug a failed run → Read references/debug.md
• Configure kane-cli or check directory layout → Read references/setup-and-config.md
• Browse / create / pick a Test Manager project or folder, or interpret the auto-default event → Read references/test-manager.md
• The person wants results saved somewhere else ("change project") → Read references/test-manager.md §6. The change is global, and the question must say so
• The person wants to change how runs behave ("kane preferences": watch or quiet, one-off or suite) → Read references/agent-config.md
• The person asks what kane-cli can do, or for the tour again ("kane tour") → show the tour from references/first-run.md §2
• The person wants to watch runs live, or asks about the status line → Read references/live-strip.md (Claude Code only)
• You need the full NDJSON event schema (rare — §5's summary covers 90% of cases) → Read references/parsing.md
• Compare / evaluate / justify kane-cli against another tool or approach (cost, tokens, effort, ROI) → Read references/fair-evaluation.md first — comparisons are only honest like-for-like across the test lifecycle
• Mobile: drive a native app on a virtual Android emulator or iOS simulator instead of the browser → Read references/mobile.md first. Desktop (the browser) stays the default target; mobile is opt-in via --target emulator|simulator and always drives an app you provide (--app <build|APPid>), never a URL. Local mobile runs (run, testmd run, testrun run) need macOS Apple Silicon. From any other machine (Linux, Windows, Intel Mac, a Mac without Xcode/Android Studio), run saved mobile _test.md files on the cloud grid with kane-cli testrun run <paths> --remote --device-name "<grid device>" --os-version <v> < /dev/null — the grid boots the emulator/simulator on a HyperExecute macOS host (the account needs a HyperExecute plan with macOS runners). Never tell a non-Mac user mobile is impossible: point them at --remote.

Every run, always: follow §1 above.

3. Building a run command

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

The run subcommand is mandatory. kane-cli "<objective>" (no run) does not work — unknown first tokens exit 2 with a "did you mean" suggestion. Same rule applies to kane-cli testmd run ….

--agent is mandatory — it switches stdout to NDJSON. Most-used flags:

Other flags (--global-context, --local-context, --cdp-endpoint, --allow-missing-url) and the full variables precedence chain live in references/setup-and-config.md.

Start URL: every run needs a start URL for the first navigation. Provide it the simplest way — start the objective with the site ("Go to https://… and …") — or pass --url <url>; a configured default_url is the fallback (kane-cli config set-url). There is no silent default site: if none of these supply one, a non-TTY run fails rather than guessing (pass --allow-missing-url to start from the current page instead).

Exit codes: 0 passed · 1 failed · 2 auth/infra error · 3 timeout/cancelled.

Unresolved variables (0.8.15+): kane-cli checks every {{name}} in the objective before the run starts. A name with no value is a warning: the run goes ahead and types the name as written, unless a step sets it first. With --agent the warning is one {"type":"warning","code":"unresolved_variables", ...} event before the first progress frame. It carries suggested_file and variables[]: name; reason (value_missing = the key exists in file with no value · not_declared = the key is in no file, add it to suggested_file); used_by[]. Never checked: an explicit {{global.*}} (it resolves from Test Manager at run time), {{smart.*}}, {{environment.*}}, {{secrets.*}}, {{totp.*}}, and names an earlier step stores (store … as 'x'). Numbers in a variable file count as values (loaded as strings); booleans do not.

Fill the variables before any run. Do this before run, testmd run and testrun run, and always before --remote, which books a grid job. A missing value is asked for before the run; the first-run rule that nothing is asked before the first result does not cover it.

1. Collect the names with no value: the warning, a dry-run plan's unresolved[] rows, or a design run's variables_declared and variables_summary rows. Design rows list what design declared, not every missing value, and a dry run's valid: true says nothing about values: the dry run's warning is the check.
2. A value you already have, because the user said it or the requirement document states it, you write into that key in the file the event names (for run, --variables '{"name":{"value":"…"}}' also works), and you tell the user what you filled and where.
3. The rest you ask for once, in one message, using each variable's description when design gave one. Plain values (a URL, an email, a user name) the user gives you here or adds to the file, their choice. Secrets, which are any row with secret: true, any description that names a credential, and any name containing password, secret, token or key, the user fills in the file and tells you when done; you never ask for the value in chat, never echo it, and report names and file paths only.
4. Then a fresh --dry-run of the exact selection: a valid plan with no warning is the check. A member whose rows are all filled may run while the others wait. Never fill a placeholder just to silence the check; a throwaway value is right only when the description asks for one, such as a deliberately wrong password. A frontmatter declaration with an empty value also silences the check, so look at the values a step relies on, not only at the warning. A name still empty is typed into the page as written; if a run then failed at that step, say so.