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 ; 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.12+): every {{name}} in the objective must have a value before the run starts. If one does not, the run refuses before anything launches — exit 2, and with --agent a single {"type":"error","code":"unresolved_variables", ...} event carrying 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[]). This is terminal — do not retry the same command. Either ask the user for the values, or write them yourself (--variables '{"name":{"value":"…"}}', or {"name":{"value":""}} stubs into suggested_file for the user to fill), then run again. There is no bypass flag. Never checked: {{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.

Examples

# One-shot
kane-cli run "Go to https://www.amazon.in and search for 'laptop'" --agent

# Headless with timeout
kane-cli run "Go to https://app.example.com and verify login page loads" --agent --headless --timeout 60

# With inline credentials
kane-cli run "Go to https://app.example.com and login with {{username}} and {{password}}" --agent \
  --variables '{"username":{"value":"alice"},"password":{"value":"s3cret","secret":true}}'

4. Writing objectives

How you phrase the objective string determines what the agent does. Four patterns:

For the full catalog — every action verb, every assertion analyze method (Visual / Textual-DOM / URL / Title / DevTools→Network/Console/Performance/Cookies/localStorage/Clipboard), direct API calls, operators, chaining, conditional/negative patterns, and worked examples — Read references/objectives-cookbook.md. Same grammar applies to one-shot kane-cli run objectives and _test.md step bodies.

| Pattern | Trigger words | Behavior |
|---|---|---|
| 🎯 Action | "go to", "click", "type", "search", "fill" | Performs browser actions |
| ✅ Assertion | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
| 📦 Extraction | "store X as 'name'" | Persists a value into run_end.final_state |
| 🔌 API call | "call", "POST/GET a URL", a pasted curl | The agent makes the HTTP request itself; "save the response as X", then assert on it in plain English: "assert the response status is 200", "store the id from the response body as 'order_id'" |

Two rules that make an objective replayable

1. End every flow in a terminal assertion. Close with a check of the resulting page state (verify the cart shows 1 item), not a bare submit or confirm the dialog. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (add a laptop to the cart) gets none. If the objective has several phases, each ends in its own check. Phrase the closing check as what is on screen once the last action completes, so it verifies with no further click or navigation; if the evidence is elsewhere, make getting there an explicit action (place the order, open Order History, then verify the newest order shows "Processing"), never verify the order succeeded by checking Order History. Two traps: confirm the dialog is an action, not a check; and verify the Submit button is visible fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
2. Intent for the actions, literal for the data. Phrase actions as goals (Log in with {{user}}) so the run absorbs layout drift; keep exact values literal or in {{variables}}. An expected-optional branch (a sometimes-there cookie banner) goes in an if/else, not assumed away.

Shape: an intent action carrying literal data, then a verify of an observable end state — Search for "{{query}}" and open the first result, then verify the title contains "{{query}}". Full grammar in references/objectives-cookbook.md §1.

The "store as" rule (critical for extraction)

Vague phrasing like "read", "tell me", "report" does NOT reliably extract data — the agent may see the value but won't capture it. Use "store as".

❌ "go to example.com and read the page title"
✅ "go to example.com, store the page title as 'page_title'"

Stored values appear in run_end.final_state and become the second results table per §1.4. Refer back to a stored value in plain English (the stored price value), never as {{price}}; {{name}} is for global variables and secrets only.

Calling APIs directly

The agent can make API calls itself — not just observe the page's traffic. Phrase an explicit call and name the response:

"Call POST https://api.example.com/login with body {...}, save the response as login,
 assert the response status is 200"

Use the response in plain English: the response status, store the id from the response body as 'order_id', and later the stored order_id value. Never {{login.status}}: {{name}} is reserved for global variables and secrets. A pasted curl works too. Full grammar in references/objectives-cookbook.md §3.5.

Chaining

Action → extraction → assertion in one objective:

"go to {{app_url}}/dashboard,
 store the welcome message as 'welcome_text',
 assert the user role in the sidebar is 'Admin'"

Dos and don'ts

| ✅ Do | ❌ Don't |
|---|---|
| Imperative verbs: "go to", "click", "store as" | Vague verbs: "check out", "look at", "explore" |
| Specific: "click the 'Add to Cart' button" | Vague: "add the item" |
| Name extractions: "store X as 'price'" | Hope for values: "tell me the price" |
| {{variables}} for credentials/URLs | Hardcode secrets in the objective |
| Plain English for values the run produces: "the stored price value", "the response status" | {{price}} / {{login.status}} for a stored value or an API response |
| Always include starting URL | Assume the agent knows where to start |
| Split mega-objectives (>15 steps) into multiple runs | Cram everything into one |

5. Parsing one-shot run --agent output — essentials

Internal reference only. Never expose these field names to the user — translate them per §1.

Stdout is NDJSON, one event per line. On kane-cli 0.8.17+ every line also carries v (contract version, 1) and ts (when it was emitted), and the first line is {"type":"stream_start","cli_version":…,"surface":"run"|"testmd"|"testrun"}. Ignore fields and event types you do not know: new ones can appear in any release. There are two shapes:

• Progress events (most events) have step (1-based), status (running at start, done/failed at completion), remark — and no type field.
• Typed events have a type field: project_folder_auto_defaulted (run-startup gate, fires before any progress when no project/folder is configured), bifurcation, child_agent_start, child_agent_end, ask_user, error (an error with code: "unresolved_variables" is a pre-run refusal and the only line — no run_end follows; handle per §3), and finally run_end.

Parsing strategy:

for each line:
  if obj.type === "run_end"  → terminal, stop parsing
  else if obj.type exists    → typed flow event (rare)
  else if obj.step exists    → progress event → summarize per §1.3

For one-shot run, build post-run logic on run_end and process exit. Saved tests and suites use their own completion events (see Command-specific completion below).

For full event schemas (bifurcation flow fields, child_agent_*, ask_user semantics, cancel/user_response outbound events, complete run_end field list), Read references/parsing.md.

kane-cli generate (§6) emits a different stream — every line is typed generate_* (no untyped progress lines), terminated by generate_done. Its schema is in references/generate-parsing.md.

The assurance conversational commands (context ingest/context extract, design tests, maintain reconcile, cover) do NOT take --agent — they take --mode agent and speak their own typed stream ending in done (open vocabulary — tolerate unknown event types; on 0.7.2+ the stream is strict — every stdout line parses, stderr silent — while on 0.7.1 a merged context ingest prints a few prose receipt lines BEFORE the stream — skip to the first { line, harmless on 0.7.2+ — and a landing-phase ingest failure ends with prose + exit 1/2 and no stream at all: a refusal, not a crash; on 0.7.2+ those failures ride the stream as error + done); for those commands only, exit 3 means paused-and-resumable, not timeout — schema in references/assurance-parsing.md, behavior in references/assurance.md. The context sync verbs (kane-cli context sync, kane-cli context push, kane-cli context pull, kane-cli context clone; kane-cli 0.8.14+) take --mode agent the same way and speak a sync_* family ending in done; there too exit 3 means a decision or a pull is needed, not a failure — references/context-sync.md. kane-cli context sync setup refuses without a terminal (TTY_REQUIRED): agents use kane-cli context sync add and kane-cli context clone.

kane-cli testrun run also emits its own typed stream (testrun_plan … terminal testrun_done) — schema in references/testrun.md. kane-cli testmd run may additionally emit test_md_evidence_ingest (replay evidence published) and test_md_bundle_sync (test bundle synced) — informational; describe in plain language, never surface raw names. The post-run evidence hint (` evidence: view locally with kane-cli evidence serve

6. Generate test cases (authoring — no browser)

kane-cli generate authors Test Scenarios → Test Cases from a plain-language description. It does not drive a browser. Use it whenever a task needs quick test cases or scenarios from a description — don't hand-author them in chat or a file. (Requirement documents + coverage accounting → assurance instead: references/assurance.md.) Reach for it to: turn a feature / requirement description into a test suite; expand or refine coverage (more edge cases, negative paths, a narrower focus); or save the Functional cases as runnable _test.md and hand them to kane-cli testmd run. Full details + event schema: Read references/generate.md.

Three explicit modes, each runs one turn then exits:

| Mode | Command |
|---|---|
| New | kane-cli generate "" --agent |
| Refine | kane-cli generate "" --refine --req --agent |
| Save | kane-cli generate --save --req --agent → writes runnable _test.md |

Launch + present — same as §1: use Bash (not Monitor), emit "Generating test cases…" before launch, then parse the output when it returns. Generate is a quick single turn — it exits on its own at generate_done.

After Bash returns, parse the NDJSON and present only what matters:

| Show | Event | How |
|------|-------|-----|
| The deliverable | generate_snapshot | Present scenarios + cases (see below) |
| Clarifications | generate_clarification | Surface the question — it needs an answer |
| Save results | generate_save_result | List files written |
| Errors | error | Surface the message |
| Skip everything else | generate_thinking, generate_progress, generate_chat, generate_start | Noise — don't narrate |

At generate_done, present the result adaptively:

• ≤ ~30 cases → a nested tree: each scenario, then its cases tagged Positive / Negative / Edge.
• more than that → a summary line + a bulleted scenario list (title + case count); expand a scenario's cases only when asked.

Then offer the next commands from the terminal line's Refine / Save hints (they carry the request id) — don't hand-build them.

Clarification → refine (do not skip): if the turn ends with a clarification, that's exit 0 — not an error. Act on it: answer it yourself, or ask your own user, then re-invoke kane-cli generate "" --refine --req --agent. Never drop a clarification.

Attach files: --files a,b,c adds local files (docs / images / PDF / CSV — up to 10, ≤ 50 MB each) as generation context on a new or --refine turn (not --save); each emits a generate_upload line before generate_start. Details in references/generate.md.

Save is Functional-only: --save writes only Functional cases to _test.md (under /.testmuai/tests by default). Non-functional cases (Security, Performance, …) are generated and shown but not saved. Run saved files with kane-cli testmd run (references/testmd.md) — that's the generate → testmd pipeline.

Internal event/field names (generate_snapshot, request_id, …) are for parsing only — never show them to the user (§5 rule). Wire schema: references/generate-parsing.md.

7. When to read which reference

| Situation | Read |
|---|---|
| User wants to save/persist/re-run a test | references/testmd.md |
| Run a suite of saved _test.md tests as one batch | references/testrun.md |
| Run a suite on the cloud grid (--remote), incl. mobile suites from any machine | references/testrun.md §Remote + references/mobile.md §Remote |
| You need quick test cases or scenarios from a description | references/generate.md |
| User has requirement docs (PRD/spec) → designed suite, coverage, or suite upkeep | references/assurance.md |
| Need the assurance NDJSON event schema (--mode agent) | references/assurance-parsing.md |
| Share the context store with a team, join one, keep stores level, or resolve a sync conflict (kane-cli 0.8.14+) | references/context-sync.md |
| Run failed, need to diagnose | references/debug.md |
| View, share, validate, or merge evidence packs | references/evidence.md |
| Multiple independent browser tasks | references/parallel.md |
| Need full NDJSON event schema (run) | references/parsing.md |
| Need the generate NDJSON event schema | references/generate-parsing.md |
| Browse / create projects or folders, or parse the auto-default event | references/test-manager.md |
| Start of every session: preflight, the ready card, sign-in | references/ready-check.md |
| A person's first session: run first, the tour, three choices | references/first-run.md |
| Any result other than a plain passed or failed run (didn't start, stopped early, product bug, saved test, suite) | references/cards.md |
| Read, save or change the person's preferences | references/agent-config.md |
| Watch runs live in the Claude Code status bar | references/live-strip.md |
| First-time install, auth, or full config | references/setup-and-config.md |
| Compare / evaluate / benchmark kane-cli vs another tool or approach (cost, tokens, effort, ROI) | references/fair-evaluation.md |

Command-specific completion

The run_end parsing strategy applies to one-shot run only. For testmd run, collect test_md_done.overall_status, duration_s, session_id, and optional share_url; embedded run_end events can finish individual steps. Local suites emit testrun_done; dispatched remote suites then emit remote_done (retain status, exit, sessions_path). generate emits generate_done. Assurance conversational agent streams end in done; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.

Progress is for live display: count only done/failed completions, retaining child and execution context when step indices repeat.

For assertion mode, optional final validation, current-page --analyzer-only checks, streaming-network capture, and code-export defaults, read Execution controls.