How to Write Kane CLI Objectives

The objective string is the most important input to Kane CLI. How you phrase it determines what the agent does and whether it succeeds. Objectives follow three patterns that you can combine freely.

Three Patterns

Pattern	Keywords	Purpose
🎯 Action	go to, click, type, fill, search, scroll, hover, select, submit	Performs browser actions
✅ Assertion	assert, verify, confirm, check that, ensure	Validates a condition: produces pass/fail
📦 Extraction	store X as ‘name’	Reads a value from the page, persists in output

Assertions and extractions are evaluated as Checkpoints. See the reference for all analyze methods (Visual, Textual, URL, Title, DevTools) and comparison operators.

Actions

Use imperative verbs to describe what the agent should do:

"go to https://example.com"
"click the 'Add to Cart' button"
"fill the email field with user@example.com"
"scroll down to the pricing section"
"select 'Premium' from the plan dropdown"

Assertions

Assertions validate page state. The test fails if the condition is not met.

"assert the page contains 'Order Confirmed'"
"verify the cart total shows '$29.99'"
"confirm no error message is visible"
"check that the Submit button is disabled"

Extractions: The “store as” Pattern

Extractions read a value from the page and store it in the run output’s final_state field. Always use the explicit store X as 'name' syntax. Vague phrasing like “tell me” or “read” does not reliably capture data. ❌ Bad: the agent may see the value but does not save it:

"go to example.com and tell me the price"
"read the page title"

✅ Good: the value is captured in final_state:

"go to example.com, store the price of the first item as 'price'"
"store the page title as 'page_title'"

Combining Patterns

Chain all three patterns in one objective:

"go to {{app_url}}/dashboard,
 store the welcome message as 'welcome_text',
 store the user role in the sidebar as 'role',
 assert the role is 'Admin',
 click the Settings button,
 assert the page contains 'Account Settings'"

This objective: navigates → extracts two values → validates a condition → performs an action → validates the result.

What Makes a Good Objective

An objective is the natural-language instruction the agent follows. The clearer the objective, the more reliably the agent completes it.

Specific. Name the site, the action, and the field values where they matter.
Action-oriented. Lead with a verb: search, open, fill, click, verify.
Ends in a check of the result. State what “done” looks like as a claim about the page, so the agent knows when to stop and a replay has something to verify.

Two habits make an objective reliable enough to save and replay.

End Every Flow in a Check of the Result

Close with an assertion about the resulting page state (verify the cart shows 1 item), not a bare submit or confirm the dialog. Without a closing check, “done” only means the agent believed it had finished. With one, the run passes or fails based on the real end state. Check the outcome, not the control that triggered it: verify the Submit button is visible fails precisely when the action worked, because the button disappears on success. If an objective has several phases (log in, then search, then check out), each phase ends in its own check. Make the closing check something the agent can see on the screen the last action leaves it on, with no further click or navigation. If the proof lives on another page, get there with an explicit action first: place the order, open Order History, then verify the newest order shows "Processing", not verify the order succeeded by checking Order History. A check that has to find its own way to the evidence is really an action hidden inside an assertion, and the route the agent picks can differ from run to run.

Say the Goal, Not the Clicks

Phrase actions as goals (Log in as {{tester}}, Complete checkout with the saved card) so a run absorbs a reordered form or a new popup instead of breaking on it. Keep exact values such as credentials, prices, and URLs literal or in {{variables}}. For a step that only sometimes appears, such as a cookie banner, write it as a condition (if a cookie banner appears, dismiss it) rather than assuming it away.

Examples

Search for "noise-cancelling headphones" on amazon.com and confirm at least
one result appears with a price under $200.

Fill the registration form at example.com/signup with name "Test User",
email "test@example.com", and a 12-character random password. Submit and
verify the confirmation page loads.

Open https://app.example.com, log in with the credentials in {{tester}},
navigate to Settings > Billing, and verify the current plan is "Pro".

Open https://app.example.com, set a cookie named session with value
{{auth_token}}, reload, and verify the dashboard loads. Then click the
"Copy invite link" button and verify the clipboard contains "/invite/".

Objectives can also set, delete, and clear cookies, localStorage, and the test clipboard directly. See Browser State Actions. Objectives can also make API calls directly: POST/GET a URL or paste a curl, save the response, and assert on it. See API Calls.

Bad to Better

	Objective
Bad	Test the login page.
Better	Open https://app.example.com/login, log in as `{{tester}}`, and verify the dashboard URL contains `/home`.

The bad version leaves “test” undefined and gives the agent no end state. The better version names the URL, the credentials, and the assertion that closes the loop.

Real Examples

kane-cli run \
  --url https://app.example.com \
  --variables-file ./creds.json \
  "fill the email field with '{{email}}',
   fill the password field with '{{password}}',
   click the Login button,
   assert the page contains 'Dashboard',
   store the logged-in username as 'username'"

Search with filters

kane-cli run \
  --url https://shop.example.com/products \
  "click the Category filter,
   select 'Electronics',
   click the Sort dropdown,
   select 'Price: Low to High',
   store the count of products as 'result_count',
   assert the result_count is greater than 0"

Settings change

kane-cli run \
  --url https://app.example.com/account \
  "click the Settings tab,
   scroll down to the Notification section,
   check the 'Email Notifications' checkbox,
   click Save,
   assert the page shows 'Settings saved successfully'"

Checkout

kane-cli run \
  --url https://shop.example.com/cart \
  --variables-file ./payment.json \
  "store the cart total as 'total',
   assert the total is greater than 0,
   click Checkout,
   fill the card number field with '{{card_number}}',
   fill the expiry field with '{{card_expiry}}',
   fill the CVC field with '{{card_cvc}}',
   click Place Order,
   assert the page contains 'Order Confirmed',
   store the order number as 'order_id'"

Assertion Types

Type	Example
Exact match	`assert the total shows '$29.99'`
Contains	`assert the page contains 'Welcome'`
State	`assert the Submit button is disabled`
Conditional	`if a cookie banner appears, dismiss it, then assert the homepage loads`
Negative	`assert no error message is visible`
Positional	`assert 'Settings' appears in the left sidebar`

Dos and Don’ts

✅ Do	❌ Don’t
Use imperative verbs: “go to”, “click”, “store as”	Use vague verbs: “check out”, “look at”, “explore”
Be specific: “click the blue ‘Submit’ in the checkout form”	Be ambiguous: “click the button”
Name extractions: “store X as ‘name‘“	Expect implicit capture: “tell me the price”
Use `{{variables}}` for credentials and URLs	Hardcode secrets in the objective
Always provide `--url`	Assume the agent knows where to start
Split objectives with >15 steps	Cram 30 steps into one objective

Objectives on Mobile

Objectives are written the same way for a native mobile app as for the browser. The difference is what the run points at: a mobile run installs an app you supply with --app, so the objective describes app screens and controls rather than a URL.

kane-cli run "Sign in and open the account tab" --target simulator --app ./builds/MyApp.zip

A mobile run cannot point at a website. WebViews inside the app under test are supported. See Mobile Testing.

Splitting Long Objectives

Objectives with more than 15 steps drift and become unreliable. Split them into multiple runs. In the Interactive TUI, the browser stays open between runs, so state carries over automatically:

> go to https://myapp.com and log in as admin
  ✓ PASSED

> navigate to User Management and create a new user "qa@example.com"
  ✓ PASSED

> verify the new user appears in the users table
  ✓ PASSED

In the Headless CLI, use --max-steps to cap each run:

kane-cli run "login flow" --url https://myapp.com --max-steps 10
kane-cli run "dashboard check" --url https://myapp.com --max-steps 10

A good rule: if your objective has more than three assert statements or more than five distinct actions, consider splitting it.

​Three Patterns

​Actions

​Assertions

​Extractions: The “store as” Pattern

​Combining Patterns

​What Makes a Good Objective

​End Every Flow in a Check of the Result

​Say the Goal, Not the Clicks

​Examples

​Bad to Better

​Real Examples

​Login flow

​Search with filters

​Settings change

​Checkout

​Assertion Types

​Dos and Don’ts

​Objectives on Mobile

​Splitting Long Objectives

Three Patterns

Actions

Assertions

Extractions: The “store as” Pattern

Combining Patterns

What Makes a Good Objective

End Every Flow in a Check of the Result

Say the Goal, Not the Clicks

Examples

Bad to Better

Real Examples

Login flow

Search with filters

Settings change

Checkout

Assertion Types

Dos and Don’ts

Objectives on Mobile

Splitting Long Objectives