Commands

These commands cover the whole cycle, plus api for spec-driven API testing. Syntax below is quoted from the repository README (v0.6.0).

Quick reference

Command	Syntax	Purpose
session	cairn session capture --url <loginUrl> --name <s>	Capture a login session once → .auth/ (cairn login shorthand; session ls / rm)
observe	cairn observe --url <u> [--session <s>]	ARIA snapshot + interactive elements + screenshot
design	cairn design --url <u> --session <s> [--checklist <f>] [--style <s>] [--fresh]	Test cases only (ATC/MTC .md + selectors), no code
automate	cairn automate --run <dir> [--validate --session <s>]	@playwright/test from ATC-* cases
promote	cairn promote --run <dir> --cases <ids> [--session <s>]	Promote manual MTC case(s) to ATC
explore	cairn explore --url <u> --session <s> [--checklist <f>] [--fresh]	Full pipeline (cases → code → validate → repair → Pilot)
api	cairn api --spec <path|url> [--base-url <u>] [--negative] [--scenarios] [--adversarial [styles]]	Generate (and, with --base-url, run + assert status/contract) happy-path, negative-schema, multi-endpoint-scenario, and adversarial cases from an OpenAPI 3.x spec
experiment	cairn experiment --dataset <d> --candidate name=file	Compare prompt versions on a dataset

Tip

No arguments opens the interactive TUI. In a non-interactive (piped/CI) shell, cairn with no arguments prints help instead.

Re-runs and --fresh

By default a 2nd+ run on the same URL reuses its previously stable cases as context and generates only the delta (new cases), so re-runs get smaller — this is intentional. Add --fresh (on design and explore) to ignore prior runs of that URL and generate a full set every time — useful for clean A/B comparisons. In the interactive TUI it’s the “Ignore prior-run experience for this URL?” toggle (default no).

Command cards

session capture auth once copy

Capture a login session once into .auth/ (a Playwright storageState); later runs reuse it with --session myapp. cairn login is a shorthand; cairn session ls / rm manage saved sessions.

$ cairn session capture --url https://app.example.com/login --name myapp

observe snapshot only copy

Navigate, wait for SPA hydration, capture an ARIA snapshot + screenshot, and extract interactive elements. Useful to sanity-check what the agent can see.

$ cairn observe --url https://app.example.com/page --session myapp

design cases only copy

Explore and write methodical test cases (ATC + MTC) — no code. Optionally steer with a checklist file and a style.

$ cairn design --url https://app.example.com/page --session myapp --checklist plan.md

automate code from ATC copy

Generate @playwright/test specs from a run’s ATC cases; with --validate, execute and self-repair them too.

$ cairn automate --run runs/<id> --validate --session myapp

promote MTC → ATC copy

Convert reviewed manual case(s) to automatable in place (.md only) — the next automate picks them up.

$ cairn promote --run runs/<id> --cases MTC-LOGIN-001

explore full pipeline copy

The whole cycle in one run, ending with a Pilot verdict.

$ cairn explore --url https://app.example.com/page --session myapp --checklist plan.md

api OpenAPI → tests copy

Generate test cases from an OpenAPI 3.x spec — happy-path, negative-schema, multi-endpoint scenarios, and adversarial (normal/curious/psycho/hacker) styles. With --base-url, run them and assert status + contract (ajv).

$ cairn api --spec openapi.yaml --base-url https://api.example.com

experiment prompt comparison copy

Compare prompt versions on a dataset, side by side.

$ cairn experiment --dataset checkout --candidate v2=prompts/design-v2.md