kaloko 0.12.2 → 0.13.0

package/src/cli.mjs

@@ -20,7 +20,7 @@ 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 } from './lib/util.mjs'
 import { packageRoot } from './lib/schema.mjs'
 import { compareRuns, formatComparison } from './lib/compare.mjs'
 import { doctor, formatDoctor } from './lib/doctor.mjs'
@@ -36,6 +36,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 +66,20 @@ 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
+  --help, -h                        Help for one command, like kaloko help <command>
+  --version, -v                     The version of kaloko (also kaloko version)
+  KALOKO_AGENT=<name>               Labels writes by an agent
+
+Exit codes: 0 done · 1 checks found problems or the command failed · 2 usage error (unknown command or option,
+missing argument)
+`
+
 const HELP = `kaloko — walk, assess and approve what your agents built, on one flow canvas
 
 Usage: kaloko <command> [options]
@@ -107,7 +122,7 @@ Project
 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]
@@ -182,7 +197,7 @@ Run
          [--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
@@ -214,15 +229,18 @@ 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] [--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)
   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] [--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
@@ -248,7 +266,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]
@@ -353,8 +371,7 @@ Design (environments with kind: design; live HTML steps in a folder)
                                     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)
 
-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) {
@@ -397,19 +414,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 +450,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 +474,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 +502,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 +517,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 +547,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.')
 }
 
 /**
@@ -943,7 +956,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 +969,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 +1000,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,7 +1060,7 @@ 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
     for (const file of args._) {
       let scenario
@@ -1078,7 +1091,7 @@ const commands = {
 
   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 +1112,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}`)
   },
@@ -1501,7 +1516,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}`) }
@@ -1581,7 +1596,7 @@ const commands = {
       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)
@@ -1666,7 +1681,7 @@ const commands = {
       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 +1705,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 +1716,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)
@@ -1889,7 +1916,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 +2062,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 +2099,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 +2110,11 @@ 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 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>.`)
     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,14 +2126,14 @@ 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`)
   },
@@ -2111,8 +2141,10 @@ 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 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 } : {}) }
+    if (days != null && !Number.isInteger(days)) throw new UsageError('--older-than takes days, e.g. 14d.')
+    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 +2157,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 +2252,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 = {}
@@ -2344,7 +2378,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 +2400,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 +2431,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 +2476,43 @@ 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 }
+    const text = commands[topic] && topic !== 'help' ? helpFor(HELP, topic, COMMON_HELP) : 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) {
+  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`)
+  say(HELP)
+  process.exitCode = 2
 }
 
 export async function main (argv) {
-  const args = parse(argv)
+  const args = parseArgs(argv)
+  if ((!args._.length && args.version) || args._[0] === 'version') { say(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); 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 }
   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 {
+    // 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 {
       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
     }

package/src/lib/cli-args.mjs

@@ -0,0 +1,139 @@
+// The command line of kaloko: arguments, the help of one command and the options each command takes. Both come from
+// the help text (src/cli.mjs HELP), so a documented option is an accepted one; HIDDEN adds aliases and options kept
+// for older scripts that the help no longer shows.
+import { UsageError } from './util.mjs'
+
+/** Options every command takes (Common options in the help). */
+export const COMMON_OPTIONS = ['run', 'config', 'org', 'json', 'help']
+
+/**
+ * Accepted options the help does not show: aliases of renamed ones (--environment is --env, --undo is --off) and
+ * options of sub-commands or older scripts. Each name here is read by the command's code.
+ */
+export const HIDDEN = {
+  prune: ['environment', 'project'],
+  runs: ['environment'],
+  screens: ['environment', 'q', 'source', 'limit'],
+  archive: ['undo'],
+  start: ['note', 'color_schemes', 'reduced_motion', 'forced_colors', 'display_modes', 'token_modes'],
+  design: ['dir', 'token', 'name', 'notes', 'branch', 'allow-pii', 'env'],
+  export: ['server-pdf', 'branch'],
+  walk: ['items', 'viewports', 'no-cache', 'record-quality', 'trace', 'offline', 'files'],
+  affected: ['no-upstream'],
+  open: ['page'],
+  mail: ['viewports'],
+  issue: ['locale', 'viewport', 'target', 'state'],
+  video: ['quality', 'card-seconds', 'viewport'],
+  spec: ['remote', 'scenario', 'version', 'step'],
+  drift: ['locale', 'viewport', 'version', 'scenario', 'step'],
+  history: ['lang'],
+  tokens: ['env', 'version'],
+  stability: ['scenario'],
+  status: ['branch'],
+  feedback: ['branch'],
+  share: ['branch', 'name', 'notes', 'notes-preview', 'strict', 'mine', 'theirs', 'lang'],
+  sync: ['mine', 'theirs', 'branch', 'strict'],
+  reference: ['branch'],
+  branch: ['from', 'git', 'take-branch', 'keep-main', 'scenario'],
+  schedule: ['force'],
+  comment: ['locale'],
+  capture: ['stability'],
+  import: ['executor', 'config', 'locales', 'viewports', 'id', 'title', 'force'],
+  browser: ['env', 'run'],
+  ci: ['wait', 'github-env', 'dotenv']
+}
+
+/** Commands whose unknown options stop the command instead of a warning: they delete, publish or change access. */
+export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment'])
+
+/**
+ * argv → { _: positional, <option>: value | true }. `--key=value` splits at the first `=` only; `--key value` takes
+ * the next word unless it is another option; `-h` and `-v` are --help and --version.
+ */
+export function parseArgs (argv) {
+  const args = { _: [] }
+  const short = { '-h': 'help', '-v': 'version' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=')
+      const k = eq < 0 ? a.slice(2) : a.slice(2, eq)
+      const next = argv[i + 1]
+      if (eq >= 0) args[k] = a.slice(eq + 1)
+      else if (next && !next.startsWith('--') && !short[next]) args[k] = argv[++i]
+      else args[k] = true
+    } else if (short[a]) args[short[a]] = true
+    else args._.push(a)
+  }
+  return args
+}
+
+/**
+ * The help text as entries: each "  <command> …" line with its continuation lines, the commands it documents (the
+ * first word, and words after " | " such as "trash … | restore") and its section heading.
+ */
+export function helpEntries (help) {
+  const out = []
+  let section = ''
+  let cur = null
+  for (const line of help.split('\n')) {
+    if (/^[A-Z]/.test(line)) { section = line; cur = null; continue }
+    const m = line.match(/^ {2}([a-z][a-z-]*)/)
+    if (m) {
+      cur = { section, commands: new Set([m[1], ...[...line.matchAll(/ \| ([a-z][a-z-]*)/g)].map((x) => x[1])]), lines: [line] }
+      out.push(cur)
+    } else if (cur && /^ {3,}\S/.test(line)) cur.lines.push(line)
+    else cur = null
+  }
+  return out
+}
+
+/** The help of one command: its entries under their section headings, then `common`; null for an unknown one. */
+export function helpFor (help, name, common = '') {
+  const entries = helpEntries(help).filter((e) => e.commands.has(name))
+  if (!entries.length) return null
+  const parts = []
+  let section = null
+  for (const e of entries) {
+    if (e.section !== section) { section = e.section; parts.push(`${parts.length ? '\n' : ''}${section}`) }
+    parts.push(...e.lines)
+  }
+  return `Usage: kaloko ${name} [options]\n\n${parts.join('\n')}\n${common ? `\n${common}` : ''}`
+}
+
+/** The options a command takes: the ones its help names, the hidden ones and the common ones. */
+export function optionsFor (help, name) {
+  const named = helpEntries(help).filter((e) => e.commands.has(name)).flatMap((e) => e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || [])
+  return new Set([...named.map((f) => f.slice(2)), ...(HIDDEN[name] || []), ...COMMON_OPTIONS])
+}
+
+/** Edit distance (insertions, deletions, substitutions) between two short words. */
+export function distance (a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    prev = row
+  }
+  return prev[b.length]
+}
+
+/** The closest of `words` to `word` within 2 edits (a typo), or null. */
+export function closest (word, words) {
+  let best = null; let d = 3
+  for (const w of words) { const x = distance(word, w); if (x < d) { d = x; best = w } }
+  return best
+}
+
+/**
+ * Options `args` has that `name` does not take: a UsageError for commands in STRICT (nothing has happened yet), a
+ * list of warning lines for the others (they run as before, without the unknown option).
+ */
+export function checkOptions (help, name, args) {
+  const known = optionsFor(help, name)
+  const unknown = Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
+  if (!unknown.length) return []
+  const lines = unknown.map((k) => { const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}` })
+  if (STRICT.has(name)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
+  return lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`)
+}