kaloko 0.12.2 → 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, 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'
@@ -36,6 +37,7 @@ import { upsertPrComment } from './lib/pr.mjs'
 import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
 import { service, serviceUrl } from './lib/service.mjs'
+import { parseArgs, helpFor, checkOptions, closest } from './lib/cli-args.mjs'
 import { issueCmd, scheduleCmd } from './lib/integrations-cli.mjs'
 import { login } from './lib/login.mjs'
 import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
@@ -65,6 +67,26 @@ import { attachAndroidWebView } from './lib/apps/webview.mjs'
 import { piiSettings, piiFindings, piiRequested, guardAllow, formatFindings } from './lib/pii.mjs'
 
 
+/** Options every command takes and the exit codes; the end of kaloko help and of the help of each command. */
+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: 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) · 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
 
 Usage: kaloko <command> [options]
@@ -88,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
@@ -99,15 +122,15 @@ 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>]
                                     [--app-version <v>] (default: the git tag on HEAD; documentation captures carry it)
-                                    Create a run directory and make it current
+                                    Create a run directory and make it current (--json: the run id and its folder)
        [--viewports iphone-15,ipad-landscape,desktop]   Viewport names of the scenario or device presets
                                     (kaloko devices lists them; <preset>-landscape turns one sideways)
        [--browsers chromium,webkit,firefox] [--color-schemes light,dark] [--reduced-motion no-preference,reduce]
@@ -120,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:
@@ -137,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
@@ -146,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
@@ -174,30 +197,32 @@ 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
                                     current run, a new run of --scenario, or an ad-hoc flow of the screens
-  status                            Show what the current run has captured
+  status [--json]                   Show what the current run has captured
                                     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)
@@ -214,25 +239,32 @@ 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] [--all] [--json]
-                                    Shared runs: the newest per scenario (with "+ N older"); --all or --scenario lists every run
+  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: --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] [--environment e] [--keep 3] [--older-than 14d] [--yes]
+  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 unless --yes
+                                    referenced and commented runs; lists what would go to the trash (--dry-run, the
+                                    default) unless --yes
   keep <run-id> [--off]             A kept run never expires and is never pruned
-  archive <scenario-id> [--undo]    Hide a retired scenario from the scenario list (admin); its runs stay reachable
+  archive <scenario-id> [--off]     Hide a retired scenario from the scenario list (admin); its runs stay reachable;
+                                    --off shows it again
   inbox [--all] [--read] [--json]   Your notifications on kaloko.app (mentions, returned runs, new runs, expiry); --read marks them read
   calibrate [--golden labels.yml] [--scenario id [--limit 30]] [--target 0.95] [--json]
                                     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,
@@ -248,7 +280,7 @@ Results
                                     Regions people drew on screenshots on kaloko.app (step detail → Mark a changing
                                     region) go into the scenario's ignore: of their steps; walk them again after
   screens [words] [--project p] [--product p] [--module m] [--scenario id] [--locale l] [--viewport v] [--device d]
-          [--status pass|partial|fail|skip] [--environment e] [--designs] [--all] [--json] [--cursor c]
+          [--status pass|partial|fail|skip] [--env e] [--designs] [--all] [--json] [--cursor c]
                                     The screen library: the newest screenshot of every step across your flows, searched
                                     by title, text, URL or id, with the canvas link of each (--designs adds design versions)
   compare [--run id] [--baseline id | --design] [--json]
@@ -268,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
 
@@ -303,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)
@@ -345,16 +381,17 @@ 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 options: --run <id|dir> (or KALOKO_RUN)  --config <file>   KALOKO_AGENT=<name> labels writes by an agent
-`
+${COMMON_HELP}`
 
 /** A comment's drawing for the terminal: "· box 120,340 300×80 px on desktop" (CSS px when the size is known). */
 export function regionText (g) {
@@ -367,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. */
@@ -397,19 +435,6 @@ async function walkVerdicts ({ prefetch, run, scenario, config, root }) {
   if (report.skipped.length) say(`  Semantic criteria not evaluated: ${[...new Set(report.skipped.map((x) => x.split(': ').slice(1).join(': ')))].slice(0, 2).join('; ')}`)
 }
 
-function parse (argv) {
-  const args = { _: [] }
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a.startsWith('--')) {
-      const [k, v] = a.slice(2).split('=')
-      if (v !== undefined) args[k] = v
-      else if (argv[i + 1] && !argv[i + 1].startsWith('--')) args[k] = argv[++i]
-      else args[k] = true
-    } else args._.push(a)
-  }
-  return args
-}
 const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : null)
 // parallel walks (#27) print each locale's lines together, in locale order: `say` writes into the running unit's buffer
 const output = new AsyncLocalStorage()
@@ -446,8 +471,15 @@ export function walkConcurrency (args, config, units, shared, cpus = availablePa
   return Math.max(1, Math.min(units, 4, Math.floor(cpus / 2)))
 }
 
+/** --env names an environment everywhere; --environment is its older spelling on runs, prune and screens. */
+const envOption = (args) => typeof args.env === 'string' ? args.env : typeof args.environment === 'string' ? args.environment : null
+/** The most runs `kaloko runs` lists in one go. */
+const RUNS_CAP = 300
+
 async function context (args) {
   const { config, root, file } = await loadConfig(process.cwd(), args.config)
+  // --org: another organization than the config's for this command (an agent working for several)
+  if (typeof args.org === 'string' && args.org) config.org = args.org
   return { config, root, file }
 }
 
@@ -463,7 +495,7 @@ async function runContext (args) {
 }
 
 function stepOf (scenario, id) {
-  if (!id) throw new UserError(`Which step? Pass --step <id>; this scenario has: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}.`)
+  if (!id) throw new UsageError(`Which step? Pass --step <id>; this scenario has: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}.`)
   const node = scenario.nodes.find((n) => n.id === id)
   if (!node) throw new UserError(`Unknown step "${id}". Steps: ${scenario.nodes.filter((n) => n.kind !== 'decision').map((n) => n.id).join(', ')}`)
   return node
@@ -491,7 +523,7 @@ async function lintOrigins (config, env, { online = false } = {}) {
  */
 async function designImport (args) {
   const [, kind, source] = args._
-  if (kind !== 'figma' || !source) throw new UserError('Usage: kaloko design import figma <file-url|key|export folder> [--scenario file] [--env <design env>] [--frames a,b] [--page name] [--map frames.json|yml] [--token-env FIGMA_TOKEN] [--tokens auto|write|skip] [--force] [--dry-run] [--publish [--notes file]]')
+  if (kind !== 'figma' || !source) throw new UsageError('Usage: kaloko design import figma <file-url|key|export folder> [--scenario file] [--env <design env>] [--frames a,b] [--page name] [--map frames.json|yml] [--token-env FIGMA_TOKEN] [--tokens auto|write|skip] [--force] [--dry-run] [--publish [--notes file]]')
   const { config, root } = await context(args)
   let run = null
   try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
@@ -506,22 +538,24 @@ async function designImport (args) {
   const viewports = Object.fromEntries(baseViewports(scope).map((v) => [v, scope.viewports[v]]))
   const tokenVar = typeof args['token-env'] === 'string' ? args['token-env'] : typeof args.token === 'string' && /^[A-Z_][A-Z0-9_]*$/.test(args.token) ? args.token : 'FIGMA_TOKEN'
   const dir = typeof args.dir === 'string' ? resolve(args.dir) : designDir(env, root)
+  // --json: standard output is the JSON alone; progress and next steps go to standard error
+  const log = args.json ? (...m) => console.error(...m) : say
   const r = await importFigma({
     source, scenario, viewports, locales: scenario.locales || ['default'], dir,
     token: process.env[tokenVar] || (tokenVar === 'FIGMA_TOKEN' ? process.env.FIGMA_ACCESS_TOKEN : null) || null,
     map: typeof args.map === 'string' ? await readMap(resolve(args.map)) : null, only: list(args.frames), page: typeof args.page === 'string' ? args.page : null,
-    tokensMode: ['write', 'skip'].includes(args.tokens) ? args.tokens : 'auto', force: !!args.force, dryRun: !!args['dry-run'], say
+    tokensMode: ['write', 'skip'].includes(args.tokens) ? args.tokens : 'auto', force: !!args.force, dryRun: !!args['dry-run'], say: log
   })
   if (args.json) say(JSON.stringify(r, null, 2))
   else say(formatImport(r, { dir: relative(process.cwd(), dir) || '.' }))
   if (args['dry-run']) return r
   const lint = await lintDesign({ dir, scenario, origins: await lintOrigins(config, env) })
-  if (lint.errors) say(`\n${formatLint(lint, { max: 10 })}`)
+  if (lint.errors) log(`\n${formatLint(lint, { max: 10 })}`)
   if (!args.publish) {
-    say(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
+    log(`\nNext: kaloko start --scenario ${relative(process.cwd(), scenarioFile)} --env ${env.name} && kaloko walk && kaloko share (or rerun with --publish).\nAccept the version on the canvas and set it as the design reference (kaloko reference --design --version <n>): implementation runs with packs: [design] are then checked against these frames.`)
     return r
   }
-  await commands.start({ ...args, _: [], scenario: scenarioFile, env: env.name })
+  await commands.start({ ...args, _: [], scenario: scenarioFile, env: env.name, json: false })
   const current = await resolveRun({ root, output: config.output })
   await commands.walk({ _: [], run: current.dir })
   await commands.share({ _: [], run: current.dir, ...(args['allow-pii'] ? { 'allow-pii': true } : {}), ...(typeof args.notes === 'string' ? { notes: args.notes } : {}), ...(typeof args.name === 'string' ? { name: args.name } : {}), ...(typeof args.branch === 'string' ? { branch: args.branch } : {}) })
@@ -534,7 +568,7 @@ async function scenarioIdOf (args, config, root) {
     return args.scenario
   }
   try { return (await resolveRun({ root, output: config.output, run: args.run })).meta.scenario.id } catch {}
-  throw new UserError('--scenario <id|file> is required when there is no current run.')
+  throw new UsageError('--scenario <id|file> is required when there is no current run.')
 }
 
 /**
@@ -923,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 {}
@@ -943,7 +1000,7 @@ const commands = {
     if (!exists) {
       let tpl = await readFile(join(packageRoot, 'templates', 'kaloko.config.yml'), 'utf8')
       if (typeof args.org === 'string') {
-        if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(args.org)) throw new UserError('--org must be the organization slug from kaloko.app (a-z, 0-9, -).')
+        if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(args.org)) throw new UsageError('--org must be the organization slug from kaloko.app (a-z, 0-9, -).')
         tpl = tpl.replace(/^org: .*$/m, `org: ${args.org}`)
       }
       if (detected) {
@@ -956,7 +1013,7 @@ const commands = {
     } else if (!existsSync(join(cwd, LEGACY_CONFIG_FILE))) say(`${CONFIG_FILE} already exists; kept.`)
     // the visual changelog (docs/DOCS-CHANGELOG.md): asked once; --docs=off|changelog|full for scripts and agents
     let docsMode = typeof args.docs === 'string' ? args.docs : null
-    if (docsMode && !['off', 'changelog', 'full'].includes(docsMode)) throw new UserError('--docs must be off, changelog or full.')
+    if (docsMode && !['off', 'changelog', 'full'].includes(docsMode)) throw new UsageError('--docs must be off, changelog or full.')
     if (!docsMode && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI && !process.env.NODE_TEST_CONTEXT) {
       const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout })
       const a = (await rl.question('Keep a visual changelog? (recommended) [Y/n] ')).trim().toLowerCase(); rl.close()
@@ -987,7 +1044,7 @@ const commands = {
       }
     } else if (!docsMode) say('Visual changelog: kaloko init --docs=changelog adds CHANGELOG.md and the config block (recommended).')
     const agent = typeof args.agent === 'string' ? args.agent : 'none'
-    if (!['claude', 'codex', 'all', 'none'].includes(agent)) throw new UserError('--agent must be claude, codex, all or none.')
+    if (!['claude', 'codex', 'all', 'none'].includes(agent)) throw new UsageError('--agent must be claude, codex, all or none.')
     const { cp, mkdir, appendFile, rm } = await import('node:fs/promises')
     const skill = join(packageRoot, 'skills', 'kaloko')
     const targets = { claude: ['.claude/skills/kaloko'], codex: ['skills/kaloko'], all: ['.claude/skills/kaloko', 'skills/kaloko'], none: [] }[agent]
@@ -1047,15 +1104,20 @@ const commands = {
   },
 
   async validate (args) {
-    if (!args._.length) throw new UserError('Usage: kaloko validate <scenario.yml>...')
+    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)] : []
@@ -1064,21 +1126,26 @@ 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) {
     const { config, root } = await context(args)
-    if (!args.scenario || !args.env) throw new UserError('Usage: kaloko start --scenario <file> --env <name>')
+    if (!args.scenario || !args.env) throw new UsageError('Usage: kaloko start --scenario <file> --env <name>')
     const scenarioFile = resolve(args.scenario)
     const scenario = await loadScenario(scenarioFile)
     const env = environment(config, args.env)
@@ -1099,9 +1166,11 @@ const commands = {
     // the product the flow documents (visual changelog): its tag, or the only product of the config
     const product = scenario.product || (Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : null)
     const { dir, meta } = await createRun({ output: config.output, scenario, scenarioFile, env, scope, git, executor, root, project, issue, appVersion: appVer, product, pii })
+    const addr = recipient(env.mail, meta.short)
+    // --json: what a script needs to pin the run (KALOKO_RUN) and find its files
+    if (args.json) { say(JSON.stringify({ run: meta.id, dir, env: env.name, readonly: !!env.readonly, locales, viewports: vpNames, project: project.slug, issue: issue || null, test_email: addr || null, pii: pii?.mode || null }, null, 2)); return }
     say(`Run ${meta.id}\n  dir: ${relative(process.cwd(), dir)}\n  env: ${env.name}${env.readonly ? ' (readonly)' : ''}\n  locales: ${locales.join(', ')}  viewports: ${vpNames.length > 12 ? `${vpNames.slice(0, 12).join(', ')} … (${vpNames.length})` : vpNames.join(', ')}${dimensionLine(scope)}\n  project: ${project.slug}${issue ? `  issue: ${issue.repo ? issue.repo + '#' : '#'}${issue.number}` : ''}`)
     if (pii) say(`  personal data: ${pii.mode === 'pseudonymize' ? 'replaced with fake values' : 'hidden'} in every capture`)
-    const addr = recipient(env.mail, meta.short)
     if (addr) say(`  test e-mail: ${addr}`)
     say(`  other agents may start runs here too: pin this one with --run ${meta.id} or KALOKO_RUN=${meta.id}`)
   },
@@ -1138,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.')
     }
   },
@@ -1232,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)`)
   },
 
@@ -1489,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
   },
 
   /**
@@ -1501,7 +1574,7 @@ const commands = {
    */
   async import (args) {
     const from = args._[0]
-    if (!from) throw new UserError('Usage: kaloko import <folder | playwright-report/ | results.json | trace.zip | walkthrough.md> [--scenario file | --adhoc] [--env e] [--locale l] [--viewport v] [--map "Title=step,…"]')
+    if (!from) throw new UsageError('Usage: kaloko import <folder | playwright-report/ | results.json | trace.zip | walkthrough.md> [--scenario file | --adhoc] [--env e] [--locale l] [--viewport v] [--map "Title=step,…"]')
     const { config, root } = await context(args)
     let source
     try { source = await readSource(resolve(from), typeof args.format === 'string' ? args.format : 'auto') } catch (e) { throw new UserError(`kaloko import: ${e.message}`) }
@@ -1568,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 })
@@ -1578,10 +1651,12 @@ 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
     }
-    if (!['github', 'gitlab'].includes(action)) throw new UserError('Usage: kaloko ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected] [--out file] [--print] [--force]\n       kaloko ci github --release [--snippet] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]')
+    if (!['github', 'gitlab'].includes(action)) throw new UsageError('Usage: kaloko ci github|gitlab [--scenario a.yml,b.yml] [--env preview] [--trigger deployment|pull_request] [--no-affected] [--out file] [--print] [--force]\n       kaloko ci github --release [--snippet] [--print] [--force]\n       kaloko ci preview-url [--wait 600] [--github-env] [--dotenv file]')
     const { config, root, file } = await context(args)
     if (args.release) {
       // release-tool integrations: record each published release on Kaloko (docs/DOCS-CHANGELOG.md)
@@ -1654,19 +1729,22 @@ 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
     }
-    if (action !== 'save' || typeof args.env !== 'string' || typeof args.account !== 'string') throw new UserError('Usage: kaloko auth save --env <name> --account <key> [--url <url>] | kaloko auth list')
+    if (action !== 'save' || typeof args.env !== 'string' || typeof args.account !== 'string') throw new UsageError('Usage: kaloko auth save --env <name> --account <key> [--url <url>] | kaloko auth list')
     const env = environment(config, args.env)
     if (env.readonly) throw new UserError(`Environment ${env.name} is readonly; saved sign-ins are for accounts on non-production environments.`)
     const account = accountFor(env, args.account, { root, config })
@@ -1690,7 +1768,7 @@ const commands = {
   },
 
   async session (args) {
-    if (args._[0] !== 'reset') throw new UserError('Usage: kaloko session reset')
+    if (args._[0] !== 'reset') throw new UsageError('Usage: kaloko session reset')
     const { config, root, env } = await runContext(args)
     const conn = await connectBrowser({ root, config, env })
     if (!conn) throw new UserError('Start the browser first: kaloko browser start')
@@ -1701,6 +1779,18 @@ const commands = {
   async status (args) {
     const { config, root, run, scenario, env } = await runContext(args)
     const caps = await readCaptures(run.dir)
+    if (args.json && env.kind !== 'design') {
+      // per step and locale: the viewports captured so far (stack steps: the pages)
+      const steps = scenario.nodes.filter((n) => n.kind !== 'decision').map((node) => ({
+        id: node.id, kind: node.kind, strategy: node.execution?.strategy || null,
+        captured: Object.fromEntries(run.meta.scope.locales.map((l) => {
+          const mine = caps.filter((c) => c.type === 'capture' && c.node === node.id && c.locale === l)
+          return [l, node.kind === 'stack' ? { pages: new Set(mine.filter((c) => c.item).map((c) => c.item)).size } : [...new Set(mine.map((c) => c.viewport).filter(Boolean))]]
+        }))
+      }))
+      say(JSON.stringify({ run: run.meta.id, dir: run.dir, env: run.meta.environment.name, locales: run.meta.scope.locales, steps }, null, 2))
+      return
+    }
     say(`Run ${run.meta.id} · ${run.meta.environment.name} · ${run.meta.scope.locales.join(', ')}`)
     if (env.kind === 'design') {
       // per step: unchanged / changed here / changed in the draft, from the folder and the last sync (#42)
@@ -1753,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) {
@@ -1760,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
   },
 
@@ -1774,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) {
@@ -1789,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: [] })
@@ -1819,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
@@ -1843,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))))
@@ -1869,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) {
@@ -1889,7 +1995,7 @@ const commands = {
 
   async design (args) {
     if (args._[0] === 'import') return designImport(args)
-    if (args._[0] !== 'lint') throw new UserError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
+    if (args._[0] !== 'lint') throw new UsageError('Usage: kaloko design lint [--env <design env> | --dir design/] [--scenario file] [--all] [--strict] [--offline] [--json]\n       kaloko design import figma <file-url|key|export folder> [--frames a,b] [--map frames.json] [--token-env FIGMA_TOKEN] [--publish]')
     const { config, root } = await context(args)
     let run = null
     try { run = await resolveRun({ root, output: config.output, run: args.run }) } catch {}
@@ -2035,7 +2141,7 @@ const commands = {
     const { config, root } = await context(args)
     let runId = args._[0] || (typeof args.run === 'string' ? args.run : null)
     if (!runId) { try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id } catch {} }
-    if (!runId) throw new UserError('Usage: kaloko signoff <run-id> [--out dir] | kaloko signoff --verify <file.json|file.pdf>')
+    if (!runId) throw new UsageError('Usage: kaloko signoff <run-id> [--out dir] | kaloko signoff --verify <file.json|file.pdf>')
     return signoffCmd({ config, args, say, client: service(config), runId })
   },
 
@@ -2072,7 +2178,7 @@ const commands = {
     if (typeof args.reopen === 'string') { await client.request('POST', `${base}/${encodeURIComponent(args.reopen)}/reopen`, {}); say(`✓ reopened ${args.reopen}`); return }
     if (typeof args.delete === 'string') { const r = await client.request('DELETE', `${base}/${encodeURIComponent(args.delete)}`); say(`✓ deleted ${args.delete}${r.kept ? ' (kept as "deleted" because others replied)' : ''}`); return }
     if (typeof args.edit === 'string') { await client.request('PATCH', `${base}/${encodeURIComponent(args.edit)}`, { note }); say(`✓ edited ${args.edit}`); return }
-    if (!note.trim()) throw new UserError('Write the comment with --note "…".')
+    if (!note.trim()) throw new UsageError('Write the comment with --note "…".')
     const status = ['rejected', 'approved'].includes(args.status) ? args.status : 'comment'
     const body = { note, status, node_id: typeof args.step === 'string' ? args.step : '', ...(typeof args.reply === 'string' ? { parent_id: args.reply } : {}), ...(typeof args.locale === 'string' ? { locale: args.locale } : {}) }
     const c = await client.request('POST', base, body)
@@ -2083,8 +2189,23 @@ const commands = {
     const { config } = await context(args)
     const client = service(config)
     const all = !!args.all || typeof args.scenario === 'string'
-    const q = new URLSearchParams({ ...(all ? {} : { latest: '1' }), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(typeof args.environment === 'string' ? { environment: args.environment } : {}), limit: '300' })
-    const runs = await client.request('GET', `/orgs/${config.org}/runs?${q}`)
+    const envName = envOption(args)
+    // --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) {
@@ -2096,23 +2217,25 @@ const commands = {
 
   async trash (args) {
     const { config } = await context(args)
-    if (!args._.length) throw new UserError('Usage: kaloko trash <run-id>...')
+    if (!args._.length) throw new UsageError('Usage: kaloko trash <run-id>...')
     const client = service(config)
     for (const id of args._) { await client.request('DELETE', `/orgs/${config.org}/runs/${encodeURIComponent(id)}`); say(`✓ ${id} moved to the trash (kaloko restore ${id} brings it back)`) }
   },
 
   async restore (args) {
     const { config } = await context(args)
-    if (args._.length !== 1) throw new UserError('Usage: kaloko restore <run-id>')
+    if (args._.length !== 1) throw new UsageError('Usage: kaloko restore <run-id>')
     await service(config).request('POST', `/orgs/${config.org}/runs/${encodeURIComponent(args._[0])}/restore`, {})
     say(`✓ ${args._[0]} restored`)
   },
 
   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 UserError('--older-than takes days, e.g. 14d.')
-    const body = { dry_run: !args.yes, keep_latest: args.keep === undefined ? 3 : Number(args.keep), ...(typeof args.scenario === 'string' ? { scenario: args.scenario } : {}), ...(typeof args.environment === 'string' ? { environment: args.environment } : {}), ...(typeof args.project === 'string' ? { project: args.project } : {}), ...(days != null ? { older_than_days: days } : {}) }
+    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 } : {}) }
     const r = await service(config).request('POST', `/orgs/${config.org}/runs/prune`, body)
     if (args.json) { say(JSON.stringify(r, null, 2)); return }
     if (!r.trash.length) { say(`Nothing to clean up (keeping the newest ${r.keep_latest} per scenario and environment).`); return }
@@ -2125,23 +2248,25 @@ const commands = {
 
   async keep (args) {
     const { config } = await context(args)
-    if (args._.length !== 1) throw new UserError('Usage: kaloko keep <run-id> [--off]')
+    if (args._.length !== 1) throw new UsageError('Usage: kaloko keep <run-id> [--off]')
     const r = await service(config).request('POST', `/orgs/${config.org}/runs/${encodeURIComponent(args._[0])}/keep`, { keep: !args.off })
     say(r.kept ? `✓ ${args._[0]} is kept: it never expires and is never pruned` : `✓ ${args._[0]} is no longer kept`)
   },
 
   async archive (args) {
     const { config } = await context(args)
-    if (args._.length !== 1) throw new UserError('Usage: kaloko archive <scenario-id> [--undo]')
-    await service(config).request('POST', `/orgs/${config.org}/scenarios/${encodeURIComponent(args._[0])}/${args.undo ? 'unarchive' : 'archive'}`, {})
-    say(args.undo ? `✓ ${args._[0]} is active again` : `✓ ${args._[0]} archived: hidden from the scenario list, its runs stay reachable (kaloko archive ${args._[0]} --undo)`)
+    if (args._.length !== 1) throw new UsageError('Usage: kaloko archive <scenario-id> [--off]')
+    // --off undoes it, as with keep and public; --undo is the older name
+    const off = !!(args.off || args.undo)
+    await service(config).request('POST', `/orgs/${config.org}/scenarios/${encodeURIComponent(args._[0])}/${off ? 'unarchive' : 'archive'}`, {})
+    say(off ? `✓ ${args._[0]} is active again` : `✓ ${args._[0]} archived: hidden from the scenario list, its runs stay reachable (kaloko archive ${args._[0]} --off)`)
   },
 
   async login (args) {
     // a project is optional: it only names the service URL, the organization and the token variable
     let config = {}
     const shell = { ...process.env } // before the project and user .env files are read
-    try { ({ config } = await context(args)) } catch (e) { if (!(e instanceof UserError)) throw e }
+    try { ({ config } = await context({ ...args, org: undefined })) } catch (e) { if (!(e instanceof UserError)) throw e }
     const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
     const inShell = shell[tokenEnv]
     const base = typeof args.url === 'string' ? args.url : serviceUrl(config)
@@ -2218,7 +2343,7 @@ const commands = {
   async draft (args) {
     const { root } = await context(args).catch(() => ({ root: process.cwd() }))
     const urls = args._.filter((u) => /^https?:\/\//.test(u))
-    if (!urls.length) throw new UserError('Usage: kaloko draft <url> [url…] (public pages of one site)')
+    if (!urls.length) throw new UsageError('Usage: kaloko draft <url> [url…] (public pages of one site)')
     const pages = []
     for (const url of urls) {
       let facts = {}
@@ -2266,6 +2391,7 @@ const commands = {
   },
 
   async export (args) {
+    exportSubcommand(args)
     const { config, root } = await context(args)
     const client = service(config)
     if (args.design) {
@@ -2336,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
   },
@@ -2344,7 +2470,7 @@ const commands = {
   /** `kaloko changelog draft`: the Unreleased entry from merged work and the screens accepted runs show differently. */
   async changelog (args) {
     const sub = args._[0]
-    if (sub !== 'draft') throw new UserError('Usage: kaloko changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]')
+    if (sub !== 'draft') throw new UsageError('Usage: kaloko changelog draft [--product p] [--since <tag|version>] [--apply] [--json] [--offline]')
     const { config, root } = await context(args)
     const { pickProduct, draftChangelog, draftText, applyToChangelog } = await import('./lib/changelog.mjs')
     const product = pickProduct(config, root, args.product)
@@ -2366,7 +2492,7 @@ const commands = {
   /** `kaloko docs publish|check`: the docs folder on Kaloko per version, and what in it needs attention. */
   async docs (args) {
     const sub = args._[0]
-    if (!['publish', 'check'].includes(sub)) throw new UserError('Usage: kaloko docs publish [--product p] [--version latest|<v>] [--reviewed] [--dry-run] [--json]\n       kaloko docs check [--product p] [--version v] [--offline] [--strict] [--json]')
+    if (!['publish', 'check'].includes(sub)) throw new UsageError('Usage: kaloko docs publish [--product p] [--version latest|<v>] [--reviewed] [--dry-run] [--json]\n       kaloko docs check [--product p] [--version v] [--offline] [--strict] [--json]')
     const { config, root } = await context(args)
     const { pickProduct } = await import('./lib/changelog.mjs')
     const docs = await import('./lib/docs.mjs')
@@ -2397,7 +2523,7 @@ const commands = {
   /** `kaloko products sync|list`: the products of the config on Kaloko, without a release; what the service has. */
   async products (args) {
     const sub = args._[0]
-    if (!['sync', 'list'].includes(sub)) throw new UserError('Usage: kaloko products sync [--product p] [--dry-run] [--json]\n       kaloko products list [--json]')
+    if (!['sync', 'list'].includes(sub)) throw new UsageError('Usage: kaloko products sync [--product p] [--dry-run] [--json]\n       kaloko products list [--json]')
     const { config, root } = await context(args)
     const lib = await import('./lib/changelog.mjs')
     if (sub === 'list') {
@@ -2442,18 +2568,86 @@ const commands = {
     say(lines.join('\n'))
   },
 
-  async help () { say(HELP) }
+  /** `kaloko help [command]`: everything, or the entries of one command with the common options. */
+  async help (args = { _: [] }) {
+    const topic = args._?.[0]
+    if (!topic) { say(HELP); return }
+    // 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)
+  }
+}
+
+/** The version of this kaloko (package.json). */
+async function packageVersion () {
+  return JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
+}
+
+/** "There is no command": the nearest command when it looks like a typo, the full help, exit code 2. */
+function unknownCommand (name, json = false) {
+  const guess = closest(name, Object.keys(commands))
+  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 = 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) } }
+}
+
+/** 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)
+  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)
+  }
 }
 
-export async function main (argv) {
-  const args = parse(argv)
+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] || (args.help ? commands.help : null)
-  if (!cmd) { console.error(`There is no command "${name}". The commands are below; kaloko help <command> explains one.\n`); say(HELP); process.exitCode = 2; return }
+  const cmd = commands[name]
+  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, args._[0]) || HELP); return }
   try {
+    for (const line of checkOptions(HELP, name, args)) console.error(line)
     await cmd(args)
   } catch (error) {
-    if (error instanceof UserError) { console.error(`${error.message}\n${SUPPORT_LINE}`); process.exitCode = 1 } else {
+    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 = 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
     }