kaloko 0.13.0 → 0.14.0

package/src/cli.mjs

@@ -20,7 +20,8 @@ import { evaluateRun, semanticPrefetch } from './lib/evaluate.mjs'
 import { buildManifest, writePreview, attentionLines } from './lib/build.mjs'
 import { stabilityCmd, pullDrawn } from './lib/stability.mjs'
 import { signoffCmd } from './lib/signoff.mjs'
-import { localized, readJson, UserError, UsageError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG } from './lib/util.mjs'
+import { localized, readJson, UserError, UsageError, globToRegExp, failureStreak, expiryNote, SUPPORT_LINE, SUPPORT_EMAIL, NO_ORG, EXIT, parseDuration } from './lib/util.mjs'
+import { noteLegacy, legacyHint, resetLegacy, legacyInUse } from './lib/legacy.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
 import { doctor, formatDoctor } from './lib/doctor.mjs'
@@ -71,13 +72,19 @@ const COMMON_HELP = `Common options (every command)
   --run <id|dir>                    The run to act on (default: the current run, or KALOKO_RUN)
   --config <file>                   Another kaloko.config.yml
   --org <slug>                      Another organization than org: in the config
-  --json                            Machine-readable output, where a command prints data
-  --help, -h                        Help for one command, like kaloko help <command>
+  --json                            Machine-readable output, where a command prints data: stdout holds only that
+                                    JSON, progress and notes go to stderr, and an error is one line on stderr:
+                                    {"error":{"message":"…","code":"…","next":"…"}} with the exit code below
+  --help, -h                        Help for one command, like kaloko help <command> (kaloko help export run: one
+                                    sub-command)
   --version, -v                     The version of kaloko (also kaloko version)
   KALOKO_AGENT=<name>               Labels writes by an agent
+  Durations (--timeout, --wait, --expires, --older-than) take a number in the option's unit or one with s, m, h or d:
+  90s, 10m, 2h, 14d
 
 Exit codes: 0 done · 1 checks found problems or the command failed · 2 usage error (unknown command or option,
-missing argument)
+missing argument) · 3 the Kaloko service cannot be reached (no connection; an HTTP error answer is 1) · 4 no token,
+or an invalid, expired or revoked one (kaloko login)
 `
 
 const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
@@ -103,9 +110,10 @@ Project
                                     Write .github/workflows/kaloko-release.yml: when release-please, changesets or
                                     semantic-release publishes a GitHub release, kaloko release records it on Kaloko
                                     (--snippet prints the step to add after the tool's own step instead)
-  ci preview-url [--wait 600] [--github-env] [--dotenv file]
+  ci preview-url [--wait 10m] [--github-env] [--dotenv file] [--json]
                                     In CI: the preview URL (KALOKO_PREVIEW_URL, the deployment event, provider
-                                    variables or the commit's GitHub deployments), the pull request and its base
+                                    variables or the commit's GitHub deployments), the pull request and its base;
+                                    --wait polls that long for the deployment (seconds, or 10m)
   login [--org <slug>] [--url <service>] [--print] [--no-open]
                                     Sign this machine in through the browser: approve the code on kaloko.app, choose
                                     the organization and what the token may do; the token (at most 30 days) goes to
@@ -114,10 +122,10 @@ Project
                                     and app tools; --fix installs missing Playwright browsers, creates the run and
                                     scenario folders, writes org: from the token and asks macOS for the desktop
                                     capture permissions
-  validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]]
+  validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]] [--json]
                                     Validate scenarios (schema + references); --coverage compares criteria with the plan
                                     With a token it also warns about scenarios the service still lists whose file is gone (--offline skips it)
-  scenarios                         List scenarios matched by the config
+  scenarios [--json]                List scenarios matched by the config
 
 Run
   start --scenario <file> --env <name> [--locales cs,en] [--viewports desktop,mobile] [--executor <name>]
@@ -135,7 +143,7 @@ Run
                                     Design environments: the token modes to render (default every mode of the set)
        [--pii redact|pseudonymize|off]   Hide personal data in every capture (placeholders or consistent fake values);
                                     default from the environment's or the scenario's pii
-  browser start|stop|status [--env e] [--headed]   One shared browser per environment (port = browser.port + index)
+  browser start|stop|status [--env e] [--headed] [--json]   One shared browser per environment (port = browser.port + index)
                                     Shared Chromium with CDP (agents, scripts and people drive it)
   browser install [--with-deps] [--browsers chromium,webkit,firefox]
                                     Download the engines of kaloko's Playwright (default Chromium; CI:
@@ -152,7 +160,7 @@ Run
                                     An app screen taken by any tool (Maestro, Appium, XCUITest, a person) with its
                                     UI dump (uiautomator/Appium XML, idb or Maestro JSON); app scenarios without
                                     --image capture the current screen of the environment's app
-  mail --step <id> [--locale l] [--to <addr>] [--subject <text>] [--timeout 60]
+  mail --step <id> [--locale l] [--to <addr>] [--subject <text>] [--timeout 60s]
        [--since <ISO date> | --any-time] [--id <mailbox message id>]
                                     Only messages received since the run started, unless --since/--any-time; --id takes one exact message
                                     Capture an e-mail from the environment's mailbox (mail.provider) as an email step
@@ -161,7 +169,7 @@ Run
   auth save --env <e> --account <key> [--url <url>]
                                     A person signs in once (SSO, MFA) in a visible browser; the session is saved
                                     for that account and walk reuses it (never uploaded)
-  auth list                         Saved sessions per environment and account, with their age
+  auth list [--json]                Saved sessions per environment and account, with their age
   walk [--steps a,b] [--locales l] [--keep-going] [--ephemeral] [--browsers webkit]
                                     Run playwright steps (execution.script) and capture them; a session stops
                                     after 3 steps in a row fail with the same error unless --keep-going
@@ -189,10 +197,11 @@ Run
                                     per locale with a chapter per step (flow), or only steps that fail (failed);
                                     also capture.record in the config or scenario, record: true on a step.
                                     A trace (actions, requests, console) is kept per step unless --no-trace
-  affected [--scenario file | --all] [--base ref] [--files a,b] [--json] [--check] [--offline]
+  affected [--scenario file | --all] [--base ref] [--files a,b] [--json] [--fail-if-none] [--offline]
                                     Which steps changed files reach, and why: framework route files against step paths
                                     and URLs captured earlier, imports, global files, i18n messages, step scripts and
-                                    affects: globs; --check exits 1 when nothing is affected
+                                    affects: globs; --fail-if-none exits 1 when nothing is affected (--check, its
+                                    older name, still works)
   import <folder | playwright-report/ | results.json | trace.zip | walkthrough.md> [--scenario file | --adhoc]
          [--env e] [--locale l] [--viewport v] [--map "Title=step,…"] [--format f] [--out file]
                                     Screenshots, recordings and traces from agents and tools as a run: into the
@@ -201,18 +210,19 @@ Run
                                     Scenarios may declare "sessions" (people in the flow); walk keeps one browser context per session and locale
 
 Results
-  evaluate                          Deterministic checks + semantic evaluator (default JEV) for all captures
+  evaluate [--json]                 Deterministic checks + semantic evaluator (default JEV) for all captures
   evaluate --recheck [--steps a,b]  After a scenario change: re-run deterministic checks on the stored HTML and ask
                                     the semantic questions again on the stored captures (no walk);
                                     console, overflow and performance keep their live result
-  build                             Write run.json and the local preview (index.html)
+  build [--json]                    Write run.json and the local preview (index.html)
   video export [--format mp4|webm|gif] [--locale l] [--steps a,b] [--lang en|cs] [--out file]
                                     The run's recordings in flow order with a title card per step (title, verdict);
                                     shared with the run on Business and up
   video list | trace --step <id> | tools
                                     Recordings and traces of the run; a step's trace as a timeline; ffmpeg, adb, simctl
   preview                           Build and print the preview path
-  share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role); files travel by content
+  share [--expires 30d] [--pr] [--json]
+                                    Upload the run to kaloko.app (KALOKO_TOKEN, tester role); files travel by content
                                     hash, so unchanged captures are not sent again and a broken-off share resumes;
                                     --pr adds or updates one comment on the branch's pull request via gh (KALOKO_PR in
                                     CI), or a note on the GitLab merge request (KALOKO_GITLAB_TOKEN)
@@ -229,12 +239,13 @@ Results
   comment --reply|--resolve|--reopen|--edit|--delete <id> [--note "…"] [--flow]
                                     Comment, answer and close feedback from the CLI (resolve with "Fixed in <commit>")
   projects [--json]                 Projects of the organization (use the slug as project: in a scenario or config)
-  runs [--scenario id] [--env e] [--all] [--json]
+  runs [--scenario id] [--env e] [--all] [--limit N] [--cursor c] [--json]
                                     Shared runs: the newest per scenario (with "+ N older"); --all or --scenario lists every
-                                    run (the newest 300; --scenario and --env narrow the list)
+                                    run: --all to the last one page by page, otherwise the newest 300; --limit N lists at
+                                    most N, --cursor c goes on where a list stopped (it prints the cursor)
   trash <run-id>... | restore <run-id>
                                     Move runs to the trash (uploader or admin) and back; restorable until purge
-  prune [--scenario id] [--env e] [--keep 3] [--older-than 14d] [--dry-run | --yes] [--json]
+  prune [--scenario id] [--env e] [--keep 3] [--older-than 14d|48h] [--dry-run | --yes] [--json]
                                     Keep the newest runs per scenario and environment plus kept, accepted, baseline,
                                     referenced and commented runs; lists what would go to the trash (--dry-run, the
                                     default) unless --yes
@@ -246,11 +257,14 @@ Results
                                     Semantic evaluator vs human labels: precision/recall per criterion at the
                                     configured thresholds and suggested thresholds (labels from a golden file or
                                     from reviewers' criterion verdicts in the service)
-  export [--run id] [--out file.zip]  Download a shared run as a zip before it expires: run.json, every file, the live
+  export run [--run id] [--out file.zip]
+                                    Download a shared run as a zip before it expires: run.json, every file, the live
                                     HTML of design steps and index.html, the canvas that opens offline from disk
-  export --scenario <id> [--accepted] [--out dir] [--locales l] [--viewports v]
+                                    (also kaloko export --run id)
+  export steps --scenario <id> [--accepted] [--out dir] [--locales l] [--viewports v]
                                     Newest capture of every step as steps/<step>/<locale>/<viewport>.<ext> plus
                                     index.json (documentation layer, Business plan); unchanged files are skipped
+                                    (also kaloko export --scenario <id>)
   public [--run id] [--off]         Make a shared run readable without sign-in (admin; testers may refresh an already public scenario)
   stability [--last 4 | --runs a,b] [--same-commit] [--apply] [--json]
                                     Regions that change on every run or move while the page is idle (clocks, ads,
@@ -286,6 +300,9 @@ Hosted runs (read-only scenarios on Kaloko's browsers, Business plan)
                                     run as you: public pages, HTTP Basic from the environment, or a saved session
                                     (--account). Steps that click or type are left out; they need the full walk
   schedule list | run <id> | pause <id> | resume <id> | remove <id> [--json]
+  schedule hook <id> [--remove] [--json]
+                                    A URL and secret that start the hosted run from a deploy (Vercel, Netlify) or
+                                    any CI job; the secret is shown once, a second call replaces it
   schedule export github --scenario <file> --env <name> [--every day|week] [--at 5] [--out file] [--print]
                                     A GitHub Actions workflow that walks the scenario on a schedule with the full CLI
 
@@ -321,12 +338,13 @@ Docs (Markdown in docs/ with step references; Diátaxis folders; translations as
                                     text was published), missing or outdated translations and user-visible changelog
                                     items without a picture; exit 1 on references or stale sections (--strict: on
                                     anything)
-  export --format md|docusaurus|vitepress|mkdocs|html|pdf|json [--product p] [--version v] [--lang l]
+  export docs [--format md|docusaurus|vitepress|mkdocs|html|pdf|json] [--product p] [--version v] [--lang l]
        [--what all|docs|changelog] [--local] [--out dir|file]
                                     The docs and changelog with their pictures as files: Markdown with an assets
-                                    folder, a Docusaurus, VitePress or MkDocs folder with sidebars, offline HTML, PDF
-                                    (printed by the browser) or the changelog as JSON; --local exports the files in
-                                    the repository instead of the published ones
+                                    folder (the default), a Docusaurus, VitePress or MkDocs folder with sidebars,
+                                    offline HTML, PDF (printed by the browser) or the changelog as JSON; --local
+                                    exports the files in the repository instead of the published ones (also kaloko
+                                    export --format <f>)
 
 Design (environments with kind: design; live HTML steps in a folder)
   start --scenario <file> --env <design env>   A run of the design folder (same scenario as development and QA)
@@ -363,13 +381,15 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     The project's token set (DTCG); check lists raw values outside it in the live folder
   branch list | create <name> [--from vN] [--git <branch>] | merge <name> [--take-branch a,b] [--keep-main c]
                                     Branches of the draft; a git-linked branch is what implementation runs of that git branch check against
-  export --live [--version n|--draft|--run id] [--out design/]
+  export live [--version n|--draft|--run id] [--out design/]
                                     Live files of a version (default: the design reference) into a folder: the handoff
-  export --live --views --run <id> [--viewport desktop] [--out design/]
+                                    (also kaloko export --live)
+  export live --views --run <id> [--viewport desktop] [--out design/]
                                     Fork into a draft: the HTML views of an app run become design steps (experimental)
-  export --design [--version n|--draft|--run id] [--out dir|file.zip]
+  export design [--version n|--draft|--run id] [--out dir|file.zip]
                                     A design version in open formats: HTML + assets, tokens.json (DTCG), scenario.yml,
-                                    screenshots and an index.html that opens from disk (default: the design reference)
+                                    screenshots and an index.html that opens from disk (default: the design reference;
+                                    also kaloko export --design)
 
 ${COMMON_HELP}`
 
@@ -384,18 +404,19 @@ export function regionText (g) {
 
 /** validate: scenarios the service still lists as active whose scenario file no longer exists here (#58). */
 async function warnRetired (args) {
-  if (args.offline) return
+  if (args.offline) return []
   let config, client
-  try { ({ config } = await context(args)); client = service(config) } catch { return } // no project or no token: offline
-  if (!config?.org) return
+  try { ({ config } = await context(args)); client = service(config) } catch { return [] } // no project or no token: offline
+  if (!config?.org) return []
   let list
-  try { list = await client.request('GET', `/orgs/${config.org}/scenarios?runs=1`) } catch { return }
+  try { list = await client.request('GET', `/orgs/${config.org}/scenarios?runs=1`) } catch { return [] }
   const gone = []
   for (const s of list || []) {
     if (s.archived || !s.file || (config.project && s.project && s.project !== config.project)) continue
     try { await readFile(resolve(s.file)) } catch { gone.push(s) }
   }
-  for (const s of gone) say(`! ${s.id}: the service lists it as active, but ${s.file} is gone here (split or renamed?). Archive it: kaloko archive ${s.id}`)
+  if (!args.json) for (const s of gone) say(`! ${s.id}: the service lists it as active, but ${s.file} is gone here (split or renamed?). Archive it: kaloko archive ${s.id}`)
+  return gone.map((s) => ({ id: s.id, file: s.file }))
 }
 
 /** The end of a walk: evaluate (the semantic answers are mostly cached by now) and say what did not pass. */
@@ -936,6 +957,29 @@ async function captureImage ({ config, run, scenario, node, locale, args }) {
 }
 
 /** walk --affected / kaloko affected: the selection for one scenario (a token adds URLs of the newest shared run). */
+/**
+ * `kaloko export run|steps|docs|live|design …`: the sub-command sets the flag form it stands for (export --live,
+ * --design, --format, --scenario), which keeps working. A flag of another kind of export is a usage mistake.
+ */
+export function exportSubcommand (args) {
+  const sub = args._[0]
+  if (sub === undefined) return null
+  // the flags of the other kinds (live and design exports take --scenario too)
+  const clashes = { run: ['live', 'design', 'format', 'scenario'], steps: ['live', 'design', 'format'], docs: ['live', 'design', 'scenario'], live: ['design', 'format'], design: ['live', 'format'] }
+  const owner = { live: 'live', design: 'design', format: 'docs', scenario: 'steps' }
+  // kaloko export <run-id>: the run named as a word, as people type it
+  if (/^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+$/.test(sub) && args.run === undefined) { args._.shift(); args.run = sub; return 'run' }
+  if (!(sub in clashes)) throw new UsageError(`kaloko export ${sub}: there is no such export. Use run, steps, docs, live or design (kaloko help export).`)
+  args._.shift()
+  const clash = clashes[sub].find((f) => args[f] !== undefined)
+  if (clash) throw new UsageError(`kaloko export ${sub} does not take --${clash}; that is kaloko export ${owner[clash]}.`)
+  if (sub === 'live') args.live = true
+  if (sub === 'design') args.design = typeof args.design === 'string' ? args.design : true
+  if (sub === 'docs' && typeof args.format !== 'string') args.format = 'md'
+  if (sub === 'steps' && typeof args.scenario !== 'string') throw new UsageError('kaloko export steps needs --scenario <id>: the flow whose steps to export.')
+  return sub
+}
+
 async function affectedSelection (args, { config, root, scenario, scenarioFile }) {
   let client = null
   try { if (!args.offline) client = service(config) } catch {}
@@ -1062,13 +1106,18 @@ const commands = {
   async validate (args) {
     if (!args._.length) throw new UsageError('Usage: kaloko validate <scenario.yml>...')
     let failed = 0
+    // --json: one entry per file with its problems, warnings and coverage; the lines below go to stderr
+    const results = []
     for (const file of args._) {
       let scenario
-      try { scenario = parseScenario(await readFile(file, 'utf8'), file) } catch (e) { if (!(e instanceof UserError)) throw e; failed++; say(`✕ ${e.message}`); continue }
+      try { scenario = parseScenario(await readFile(file, 'utf8'), file) } catch (e) { if (!(e instanceof UserError)) throw e; failed++; say(`✕ ${e.message}`); results.push({ file, ok: false, problems: [e.message], warnings: [] }); continue }
       const problems = validateScenario(scenario)
       if (!problems.length) expandPacks(scenario)
       if (problems.length) { failed++; say(`✕ ${file}\n  - ${problems.join('\n  - ')}`) } else say(`✓ ${file}`)
-      if (!problems.length) for (const w of scenarioWarnings(scenario)) say(`  ! ${w}`)
+      const warnings = problems.length ? [] : scenarioWarnings(scenario)
+      for (const w of warnings) say(`  ! ${w}`)
+      const entry = { file, id: scenario.id || null, ok: !problems.length, problems, warnings }
+      results.push(entry)
       if (args.coverage) {
         // the plan is scenario.source (relative to the working directory or to the scenario file), or --source
         const candidates = typeof args.source === 'string' ? [resolve(args.source)] : scenario.source ? [resolve(scenario.source), resolve(file, '..', scenario.source), resolve(file, '..', '..', scenario.source)] : []
@@ -1077,16 +1126,21 @@ const commands = {
         if (!plan) { say(`  · no acceptance plan found (${scenario.source ? `source: ${scenario.source}` : 'scenario has no source'}); pass --source <ACCEPTANCE.md>`); continue }
         const cov = coverage(scenario, plan)
         say(formatCoverage(file, cov))
+        entry.coverage = { missing: cov.missing }
         if (cov.missing.length) process.exitCode = 1
       }
     }
     if (failed) process.exitCode = 1
-    await warnRetired(args)
+    const retired = await warnRetired(args)
+    if (args.json) say(JSON.stringify({ ok: !failed && process.exitCode !== 1, files: results, retired }, null, 2))
   },
 
   async scenarios (args) {
     const { config, root } = await context(args)
-    for (const s of await catalogFor(config, root)) say(`${s.id.padEnd(36)} ${s.kind.padEnd(5)} ${String(s.runs.length).padStart(3)} runs  ${s.file}`)
+    const all = await catalogFor(config, root)
+    // --json: id, title, kind, file and the local runs (newest first) of every scenario the config matches
+    if (args.json) { say(JSON.stringify(all, null, 2)); return }
+    for (const s of all) say(`${s.id.padEnd(36)} ${s.kind.padEnd(5)} ${String(s.runs.length).padStart(3)} runs  ${s.file}`)
   },
 
   async start (args) {
@@ -1153,6 +1207,7 @@ const commands = {
       say(await stopBrowser({ root, config, env }) ? `Browser stopped${env ? ` (${env.name})` : ' (all environments)'}.` : 'Browser was not running.')
     } else {
       const states = await allStates({ root, config })
+      if (args.json) { say(JSON.stringify(states.map((s) => ({ environment: s.environment, cdp: s.cdp, pid: s.pid, readonly: !!s.readonly })), null, 2)); return }
       say(states.length ? states.map((s) => `${s.environment}: ${s.cdp} (pid ${s.pid})${s.readonly ? ', readonly' : ''}`).join('\n') : 'No shared browser is running.')
     }
   },
@@ -1247,7 +1302,7 @@ const commands = {
     let since
     if (args['any-time']) since = null
     else if (typeof args.since === 'string') { const t = Date.parse(args.since); if (Number.isNaN(t)) throw new UserError(`--since ${args.since} is not a date (ISO 8601, e.g. 2026-09-27T10:00).`); since = new Date(t).toISOString() }
-    const results = await captureMail({ config, root, run, env, scenario, node, locale, to, subject, timeoutMs: (Number(args.timeout) || 60) * 1000, viewports: list(args.viewports), message, since, id: typeof args.id === 'string' ? args.id : null })
+    const results = await captureMail({ config, root, run, env, scenario, node, locale, to, subject, timeoutMs: (parseDuration(args.timeout, 's', 'timeout') || 60) * 1000, viewports: list(args.viewports), message, since, id: typeof args.id === 'string' ? args.id : null })
     say(`✓ ${node.id} ${locale}: "${results.subject}" → ${results.count} viewport(s)`)
   },
 
@@ -1504,10 +1559,13 @@ const commands = {
       out.push({ scenario: scenario.id, file: relative(root, file), base: r.base, changed: r.files, runs: r.runs, ...r.sel, walk: selectedIds(scenario, r.sel) })
       if (!args.json) say(formatAffected(r.sel, { scenario, base: r.base, changed: r.files.length }) + '\n')
     }
+    const failIfNone = !!(args['fail-if-none'] || args.check)
     if (args.json) say(JSON.stringify(targets.length === 1 && typeof args.scenario === 'string' ? out[0] : out, null, 2))
-    else if (!args.check) say(`Walk them with: kaloko walk --affected${args.base ? ` --base ${args.base}` : ''} (after kaloko start)`)
-    // --check: exit code 1 when nothing is affected (CI skips the scenario)
-    if (args.check && !out.some((o) => o.walk.length && !o.none)) process.exitCode = 1
+    else if (!failIfNone) say(`Walk them with: kaloko walk --affected${args.base ? ` --base ${args.base}` : ''} (after kaloko start)`)
+    // --check is the older name of --fail-if-none: it works the same and says so once
+    if (args.check && !args['fail-if-none']) console.error('! kaloko affected --check is now --fail-if-none: it works the same; rename it in your CI when you next touch it.')
+    // --fail-if-none: exit code 1 when nothing is affected (CI skips the scenario)
+    if (failIfNone && !out.some((o) => o.walk.length && !o.none)) process.exitCode = 1
   },
 
   /**
@@ -1583,7 +1641,7 @@ const commands = {
     const action = args._[0]
     if (action === 'preview-url') {
       const err = (m) => console.error(m)
-      const preview = await findPreview({ wait: Number(args.wait) || 0, say: err })
+      const preview = await findPreview({ wait: parseDuration(args.wait, 's', 'wait') || 0, say: err })
       const pr = await pullRequestOf().catch(() => null)
       if (!preview) throw new UserError('No preview URL found. Set KALOKO_PREVIEW_URL, or let Vercel, Netlify or Cloudflare Pages report deployments to GitHub (the workflow needs deployments: read).')
       const lines = envLines({ preview, pr })
@@ -1593,6 +1651,8 @@ const commands = {
       }
       if (typeof args.dotenv === 'string') await writeEnvFile(resolve(args.dotenv), lines)
       err(`Preview ${preview.url} (from ${preview.source})${pr?.number ? `, pull request #${pr.number}${pr.base ? ` into ${pr.base}` : ''}` : ''}`)
+      // --json: the URL, where it came from and the pull request, with the variables the env lines set
+      if (args.json) { say(JSON.stringify({ url: preview.url, source: preview.source, pr: pr?.number || null, base: pr?.base || null, head: pr?.head || null, env: Object.fromEntries(lines.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)])) }, null, 2)); return }
       console.log(preview.url)
       return
     }
@@ -1669,15 +1729,18 @@ const commands = {
     const { stat, mkdir, writeFile: write, chmod } = await import('node:fs/promises')
     if (action === 'list') {
       const rows = []
+      const items = []
       for (const name of Object.keys(config.environments)) {
         let env
         try { env = environment(config, name) } catch { continue }
         for (const key of Object.keys(env.accounts || {})) {
           const file = accountFor(env, key, { root, config }).storage_state
           const st = await stat(file).catch(() => null)
+          items.push({ environment: name, account: key, saved: !!st, saved_at: st ? new Date(st.mtimeMs).toISOString() : null, file: relative(process.cwd(), file) })
           rows.push(`${name.padEnd(12)} ${key.padEnd(16)} ${st ? `saved ${Math.round((Date.now() - st.mtimeMs) / 36e5)} h ago · ${relative(process.cwd(), file)}` : 'no saved session'}`)
         }
       }
+      if (args.json) { say(JSON.stringify(items, null, 2)); return }
       say(rows.length ? rows.join('\n') : 'No accounts in kaloko.config.yml (environments.<env>.accounts).')
       return
     }
@@ -1780,6 +1843,11 @@ const commands = {
       say(`Semantic criteria not evaluated:\n  - ${[...byReason].slice(0, 8).map(([why, where]) => `${where.length > 1 ? `${where.length} captures (${where.slice(0, 3).join(', ')}${where.length > 3 ? ', …' : ''})` : where[0]}: ${why}`).join('\n  - ')}`)
     }
     if (report.outdated.length) say(`Criteria changed after capture of ${report.outdated.join(', ')}: not evaluated. Run "kaloko evaluate --recheck --steps ${report.outdated.join(',')}": it rechecks the stored captures against the new criteria, deterministic and semantic, without walking again.`)
+    // --json: the counts and every verdict a person or agent has to act on (fail, needs_review)
+    if (args.json) {
+      const pick = (f) => ({ step: f.node, ...(f.item ? { item: f.item } : {}), locale: f.locale, viewport: f.viewport, criterion: f.id, verdict: f.verdict, why: f.why || null, fix: f.fix || null })
+      say(JSON.stringify({ run: run.meta.id, evaluated: report.evaluated, semantic: { model: report.model, calls: report.semantic_calls, cached: report.semantic_cached, via: report.via.qawalk ? 'kaloko' : report.via['own-key'] ? 'own-key' : null }, vision: report.vision || null, triage: report.triage || null, findings: (report.findings || []).filter((f) => f.verdict === 'fail' || f.verdict === 'needs_review').map(pick), skipped: report.skipped, outdated: report.outdated }, null, 2))
+    }
   },
 
   async build (args) {
@@ -1787,8 +1855,11 @@ const commands = {
     const manifest = await buildManifest({ run, scenario, config, root, catalog: await catalogFor(config, root) })
     const file = await writePreview({ run, manifest })
     const s = manifest.summary
+    const why = attentionLines(manifest)
+    // --json: the run id, its summary, the preview file and the AI verdicts to act on
+    if (args.json) { say(JSON.stringify({ run: manifest.id, summary: s, preview: file, manifest: join(run.dir, 'run.json'), attention: why.map((l) => l.trim()) }, null, 2)); return file }
     say(`${manifest.id}: ${s.pass} pass · ${s.partial} partial · ${s.fail} fail · ${s.skip} not checked\nPreview: ${file}`)
-    const why = attentionLines(manifest); if (why.length) say(`AI verdicts to act on (score and why):\n${why.join('\n')}`)
+    if (why.length) say(`AI verdicts to act on (score and why):\n${why.join('\n')}`)
     return file
   },
 
@@ -1801,7 +1872,7 @@ const commands = {
 
   async preview (args) {
     const file = await commands.build(args)
-    say(pathToFileURL(file).href)
+    if (!args.json) say(pathToFileURL(file).href)
   },
 
   async share (args) {
@@ -1816,6 +1887,7 @@ const commands = {
       const meta = await readJson(join(run.dir, 'meta.json'))
       meta.shared = { url: v.url, at: new Date().toISOString(), version: v.version, run: v.id }
       await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
+      if (args.json) say(JSON.stringify({ run: v.id, url: v.url, version: v.version ?? null, scenario: scenario.id }, null, 2))
       return
     }
     let manifest = await buildManifest({ run, scenario, config, root, catalog: [] })
@@ -1846,7 +1918,10 @@ const commands = {
     if (findings.length && strict && !args['allow-pii']) throw new UserError(`Not shared: the run holds ${findings.length} unmasked personal data value(s):\n${formatFindings(findings)}\nMask them (capture.mask in the scenario, or pii: redact for automatic detection) and capture the steps again. Values that are not personal data, such as a company contact, go under pii.allow in kaloko.config.yml. To share anyway: kaloko share --allow-pii.`)
     if (findings.length && strict) say(`Sharing ${findings.length} unmasked personal data value(s), as --allow-pii says:\n${formatFindings(findings, 5)}`)
     else if (findings.length) say(`This run shows ${findings.length} value(s) that look like personal data:\n${formatFindings(findings, 5)}\nShared anyway, because the run does not hide personal data. To hide it, add pii: redact to the scenario or the environment; values that are not personal data go under pii.allow in kaloko.config.yml.`)
-    const days = Number(args.expires) || config.share?.expires_days || 30
+    // --expires: days (30), or with a unit that makes whole days (whole days: 48h is 2)
+    const asked = parseDuration(args.expires, 'd', 'expires')
+    if (asked != null && (!Number.isInteger(asked) || asked < 1)) throw new UsageError(`--expires counts whole days: ${args.expires} is ${Math.round(asked * 100) / 100} days. Use 30, 30d or 72h.`)
+    const days = asked || config.share?.expires_days || 30
     // by content hash (#28): files the organization already stores (earlier runs, an interrupted share) are not sent
     let entries = await hashFiles(run.dir, [...files])
     // a recording above the service's file limit stays local (with its poster and preview), the rest is shared
@@ -1870,7 +1945,7 @@ const commands = {
     } catch (e) { if (e instanceof UserError && /limit|quota/.test(e.message)) throw e }
     const created = await client.request('POST', `/orgs/${config.org}/runs?expires_days=${days}`, manifest)
     await writeFile(join(run.dir, PROGRESS_FILE), JSON.stringify({ run: manifest.id, started_at: new Date().toISOString() }) + '\n').catch(() => {})
-    const up = await uploadRunFiles({ client, org: config.org, runId: manifest.id, dir: run.dir, entries, missing, say })
+    const up = await uploadRunFiles({ client, org: config.org, runId: manifest.id, dir: run.dir, entries, missing, say, ...(args.json ? { write: (t) => process.stderr.write(t) } : {}) })
     if (up.mode === 'blobs') say(`  ${up.uploaded} new file(s) sent (${fmtBytes(up.bytes)}), ${up.reused} unchanged file(s) reused`)
     // experimental HTML views (#42): their bundles travel as blobs and attach to the run as revisions
     const viewIds = new Set(manifest.nodes.flatMap((n) => Object.values(n.captures || {}).flatMap((vps) => Object.values(vps).map((c) => c.view?.revision).filter(Boolean))))
@@ -1896,10 +1971,14 @@ const commands = {
     if (review) say(review)
     const capped = expiryNote(days, created.expires_days)
     if (capped) say(`Note: ${capped}`)
+    let prComment = null
     if (args.pr) {
       const r = await upsertPrComment({ manifest, url: fin.url, cwd: root })
+      prComment = r.ok ? { action: r.action, url: r.url } : { skipped: r.reason }
       say(r.ok ? `PR comment ${r.action}: ${r.url}` : `PR comment skipped: ${r.reason}.`)
     }
+    // --json: what a script needs next, the run id and its canvas URL (the lines above went to stderr)
+    if (args.json) say(JSON.stringify({ run: manifest.id, url: fin.url, scenario: scenario.id, files: files.size, expires_days: created.expires_days, review: fin.review || null, ...(args.pr ? { pr_comment: prComment } : {}) }, null, 2))
   },
 
   async sync (args) {
@@ -2111,10 +2190,22 @@ const commands = {
     const client = service(config)
     const all = !!args.all || typeof args.scenario === 'string'
     const envName = envOption(args)
-    const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(envName ? { environment: envName } : {}), limit: String(RUNS_CAP) })
-    const runs = await client.request('GET', `/orgs/${config.org}/runs?${q}`)
-    // the service answers at most RUNS_CAP: say so (on stderr, so --json stays one JSON array)
-    if (runs.length >= RUNS_CAP) console.error(`Showing the newest ${RUNS_CAP}; there may be more. Narrow the list with --scenario <id> or --env <name>.`)
+    // --limit N: at most N runs; --all follows the service's cursors to the last run, otherwise the newest RUNS_CAP;
+    // --cursor continues where an earlier list stopped (the cursor it printed)
+    if (args.limit !== undefined && !(Number(args.limit) >= 1)) throw new UsageError('--limit takes a number of runs, e.g. --limit 50.')
+    const want = args.limit !== undefined ? Math.floor(Number(args.limit)) : args.all ? Infinity : RUNS_CAP
+    const runs = []
+    let cursor = typeof args.cursor === 'string' ? args.cursor : null
+    let next = null
+    do {
+      const page = Math.min(1000, want - runs.length)
+      const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(envName ? { environment: envName } : {}), limit: String(page), ...(cursor ? { cursor } : {}) })
+      const got = await client.page(`/orgs/${config.org}/runs?${q}`)
+      runs.push(...got.data)
+      next = cursor = got.next
+    } while (next && runs.length < want)
+    // more runs than were listed: say how to go on (on stderr, so --json stays one JSON array)
+    if (next) console.error(`Showing ${runs.length}; there are more. kaloko runs${args.all ? ' --all' : ''}${typeof args.scenario === 'string' ? ` --scenario ${args.scenario}` : ''}${envName ? ` --env ${envName}` : ''} --cursor ${next} lists the next ones${all && !args.all ? ', --all every one' : ''}.`)
     if (args.json) { say(JSON.stringify(runs, null, 2)); return }
     if (!runs.length) { say('No shared runs match.'); return }
     for (const r of runs) {
@@ -2140,8 +2231,8 @@ const commands = {
 
   async prune (args) {
     const { config } = await context(args)
-    const days = typeof args['older-than'] === 'string' ? Number(args['older-than'].replace(/d$/, '')) : null
-    if (days != null && !Number.isInteger(days)) throw new UsageError('--older-than takes days, e.g. 14d.')
+    const days = parseDuration(args['older-than'], 'd', 'older-than')
+    if (days != null && !Number.isInteger(days)) throw new UsageError(`--older-than counts whole days, e.g. 14, 14d or 48h; ${args['older-than']} is ${Math.round(days * 100) / 100} days.`)
     if (args.yes && args['dry-run']) throw new UsageError('--dry-run and --yes contradict each other: --dry-run (the default) lists, --yes moves runs to the trash.')
     const envName = envOption(args)
     const body = { dry_run: !args.yes, keep_latest: args.keep === undefined ? 3 : Number(args.keep), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(envName ? { environment: envName } : {}), ...(typeof args.project === 'string' ? { project: args.project } : {}), ...(days != null ? { older_than_days: days } : {}) }
@@ -2300,6 +2391,7 @@ const commands = {
   },
 
   async export (args) {
+    exportSubcommand(args)
     const { config, root } = await context(args)
     const client = service(config)
     if (args.design) {
@@ -2370,7 +2462,7 @@ const commands = {
     const engines = []
     const scenarios = []
     for (const f of await scenarioFiles(config, root).catch(() => [])) { try { const s = yaml.load(await readFile(f, 'utf8')) || {}; engines.push(...(s.browsers || [])); scenarios.push({ file: relative(root, f), product: s.product || null, module: s.module || null }) } catch {} }
-    const r = await doctor({ config, root, file, fix: !!args.fix, engines, scenarios })
+    const r = await doctor({ config, root, file, fix: !!args.fix, engines, scenarios, legacy: legacyInUse() })
     say(args.json ? JSON.stringify(r, null, 2) : formatDoctor(r))
     if (!r.ok) process.exitCode = 1
   },
@@ -2480,7 +2572,8 @@ const commands = {
   async help (args = { _: [] }) {
     const topic = args._?.[0]
     if (!topic) { say(HELP); return }
-    const text = commands[topic] && topic !== 'help' ? helpFor(HELP, topic, COMMON_HELP) : null
+    // kaloko help export run: the entries of that sub-command (all of the command's when it has none by that name)
+    const text = commands[topic] && topic !== 'help' ? helpFor(HELP, topic, COMMON_HELP, args._?.[1]) : null
     if (text) { say(text); return }
     unknownCommand(topic)
   }
@@ -2492,27 +2585,69 @@ async function packageVersion () {
 }
 
 /** "There is no command": the nearest command when it looks like a typo, the full help, exit code 2. */
-function unknownCommand (name) {
+function unknownCommand (name, json = false) {
   const guess = closest(name, Object.keys(commands))
-  console.error(`There is no command "${name}".${guess ? ` Did you mean kaloko ${guess}?` : ''} The commands are below; kaloko help <command> explains one.\n`)
+  const message = `There is no command "${name}".${guess ? ` Did you mean kaloko ${guess}?` : ''}`
+  if (json) { console.error(JSON.stringify(jsonError(new UsageError(message, { next: 'kaloko help lists the commands.' })))); process.exitCode = EXIT.usage; return }
+  console.error(`${message} The commands are below; kaloko help <command> explains one.\n`)
   say(HELP)
-  process.exitCode = 2
+  process.exitCode = EXIT.usage
+}
+
+/** A line of output that is a JSON document (the --json answer), told apart from progress and notes. */
+const isJsonText = (text) => { const t = text.trim(); if (!/^[[{]/.test(t)) return false; try { JSON.parse(t); return true } catch { return false } }
+
+/** The --json error: { error: { message, code, next } } (help/reference/cli.md → Machine output). */
+export function jsonError (error) {
+  const usage = error instanceof UsageError
+  return { error: { message: error.reason || error.message, code: typeof error.code === 'string' ? error.code : usage ? 'usage' : error instanceof UserError ? 'failed' : 'internal', next: error.next || (usage ? 'kaloko help <command> shows how to use it.' : null) } }
 }
 
-export async function main (argv) {
+/** The exit code of an error: 2 usage, 3 the service cannot be reached, 4 no or a bad token, else 1. */
+export const exitCodeOf = (error) => error?.exitCode || (error instanceof UsageError ? EXIT.usage : EXIT.failed)
+
+/**
+ * Runs one command. `bin` is the name it was started by: the qawalk command from before the rename still works.
+ * With --json, stdout carries only the JSON answer: every other line goes to stderr, and an error is one JSON line
+ * on stderr ({ error: { message, code, next } }) with the same exit code as without --json.
+ */
+export async function main (argv, { bin = 'kaloko' } = {}) {
+  resetLegacy()
+  if (bin === 'qawalk') noteLegacy('the qawalk command', 'kaloko')
   const args = parseArgs(argv)
-  if ((!args._.length && args.version) || args._[0] === 'version') { say(await packageVersion()); return }
+  const json = !!args.json
+  const stdout = console.log
+  if (json) console.log = (...m) => (isJsonText(m.join(' ')) ? stdout : console.error)(...m)
+  try {
+    await runCommand(args, json)
+  } finally {
+    if (json) console.log = stdout
+    const hint = legacyHint()
+    if (hint) console.error(hint)
+  }
+}
+
+async function runCommand (args, json) {
+  if ((!args._.length && args.version) || args._[0] === 'version') { say(json ? JSON.stringify({ version: await packageVersion() }) : await packageVersion()); return }
   const name = args._.shift() || 'help'
   const cmd = commands[name]
-  if (!cmd) { if (args.help) say(HELP); else unknownCommand(name); return }
+  if (!cmd) { if (args.help) say(HELP); else unknownCommand(name, json); return }
   // kaloko <command> --help: the command's help instead of running it
-  if (args.help && name !== 'help') { say(helpFor(HELP, name, COMMON_HELP) || HELP); return }
+  if (args.help && name !== 'help') { say(helpFor(HELP, name, COMMON_HELP, args._[0]) || HELP); return }
   try {
     for (const line of checkOptions(HELP, name, args)) console.error(line)
     await cmd(args)
   } catch (error) {
+    const known = error instanceof UserError
+    if (json) {
+      // the reason in one JSON line on stderr, the documented exit code; a bug also prints its stack before it
+      if (!known) console.error(error?.stack || String(error))
+      console.error(JSON.stringify(jsonError(error)))
+      process.exitCode = exitCodeOf(error)
+      return
+    }
     // a usage mistake: the command's help says what is wrong; no support line, exit code 2
-    if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = 2 } else if (error instanceof UserError) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = 1 } else {
+    if (error instanceof UsageError) { console.error(`${error.message}${/kaloko help /.test(error.message) ? '' : `\nkaloko help ${name} shows how to use it.`}`); process.exitCode = EXIT.usage } else if (known) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = exitCodeOf(error) } else {
       console.error(`Kaloko stopped on an unexpected error (a bug on our side). Send the output below to ${SUPPORT_EMAIL} with the command you ran.`)
       throw error
     }