CLI commands

Every command of the kaloko CLI with what it does. Run them with npx kaloko <command> in a project that has the package installed. npx kaloko help prints the same list with every option.

Options that work everywhere: --run <id|dir> (or KALOKO_RUN) picks the run, --config <file> the config file, --json prints data for scripts (Machine output below), and KALOKO_AGENT=<name> labels what an agent writes. kaloko help <command> explains one command, kaloko help export run one sub-command.

Set up a project

CommandWhat it does
kaloko initCreates kaloko.config.yml, installs the skill for Claude Code or Codex (--agent), detects the framework, dev server, languages and main routes, drafts a first scenario; --docs=off|changelog|full sets up the changelog and the docs folders. --project, --project-name and --product name the project on Kaloko. In a repository with several sites it lists them and guesses no routes: --site picks one, --base-url reads the pages from the running site (sitemap, then the home page links), --skeleton writes a scenario with a TODO
kaloko init --seo <site>A weekly SEO and answer-engine monitor of a public site: reads robots.txt and the sitemaps, finds the languages and the biggest content families (the first path segment, translated per language) and writes qa/flows/seo-<site>.yml with one rotating stack step per family. --families, --limit (pages per family, language and week), --packs seo,aeo,a11y,perf, --env, --out, --force
kaloko loginSigns this machine in through the browser and saves a token (at most 30 days) to ~/.config/kaloko/.env; --print prints it instead
kaloko doctorChecks Node, Chrome, the config, environments, browser ports, the token, the evaluator key and app tools; --fix asks macOS for capture permissions
kaloko draft <url…>Drafts a first plan and a read-only scenario for public pages, with the seo, a11y, perf and console packs
kaloko validate <file…>Checks scenarios against the schema and their references; --coverage compares the criteria with the acceptance plan; --json lists the problems per file
kaloko scenariosLists the scenarios the config matches
kaloko ci github|gitlabWrites a workflow that walks what each pull request affects on its preview deployment and comments on it
kaloko ci github --releaseWrites a workflow that records every release your release tool publishes
kaloko ci preview-urlIn CI: finds the preview URL, the pull request and its base
kaloko ci planIn CI or a coding agent's sandbox: tells the Kaloko check on the pull request which scenarios this commit reaches

Walk and capture

CommandWhat it does
kaloko startCreates a run of --scenario on --env and makes it current; --locales, --viewports, --browsers, --color-schemes, --devices and more choose what to capture; --states limits the step states, --token-modes the token modes of a design; --pii redact or pseudonymize hides personal data in every capture; --ref CC-2026-001 (repeat it, or KALOKO_REFS in CI) names the records the run serves, --purpose dry_run, formal or smoke (KALOKO_PURPOSE) says why it was walked
kaloko walkRuns the Playwright steps and captures them, then evaluates; --affected, --record, --heal, --stability N, --concurrency N, --ephemeral
kaloko capture --step <id>Captures the current page for a step; --state empty as one of its states, --crop attaches an element, --image imports a screen taken by another tool
kaloko open --step <id>Opens the step's URL in the shared browser
kaloko mail --step <id>Captures an e-mail from the environment's mailbox, or a saved message with --file
kaloko browser start|stop|statusOne shared browser per environment that agents, scripts and people drive
kaloko browser installDownloads the browser engines (--browsers chromium,webkit,firefox)
kaloko devicesLists the device presets you can use as viewports
kaloko session resetStarts as a new visitor: clears cookies and storage in the shared browser
kaloko auth saveA person signs in once (SSO, MFA) and the walk reuses the session; kaloko auth list shows saved sessions
kaloko affectedSays which steps the changed files reach, and why; --fail-if-none exits 1 when none (--check is its older name)
kaloko import <path>Lays out screenshots, Playwright reports, traces or a walkthrough as a run
kaloko statusShows what the current run has captured

Results and review

CommandWhat it does
kaloko evaluateRuns the deterministic checks and the semantic evaluator for all captures; --recheck after a scenario change, --budget N for at most N paid evaluator calls
kaloko buildWrites run.json and the local preview
kaloko previewBuilds the preview and prints its path
kaloko shareUploads the run to kaloko.app; --pr comments on the pull request or merge request. In a run that hides personal data, an unmasked e-mail, phone number, birth number or IBAN stops the upload with the step and element (--allow-pii uploads anyway); other runs upload with a warning
kaloko reviewWhat a person still has to decide on a shared run, and the review-mode link
kaloko healthThe health of a run (advisory checks of packs) and what changed since the previous run; --remote for the shared run, --fail-on error to make errors exit 1
kaloko health adopt <step>:<check>Makes a health check an acceptance criterion of the step in the scenario file, as is or with --text
kaloko health pullWrites the checks people adopted on kaloko.app into the scenario file
kaloko feedbackOpen comments from reviewers, returned steps first
kaloko commentComments, replies, resolves and reopens feedback from the terminal
kaloko compareA text diff of two runs: statuses, verdicts, scores and evidence
kaloko stabilityFinds regions that change on every run; --apply adds them to the scenario, --pull brings in regions drawn on kaloko.app
kaloko calibrateCompares the semantic evaluator with human labels and suggests thresholds
kaloko signoff <run-id>Downloads the signed acceptance record of an accepted run; --package downloads the evidence package of any shared run (record, trace matrix, audit trail, screenshots, signed manifest); --verify <file> checks a record or a package without a token
kaloko evidence <run-id>The evidence of a run, or of a release with --release <version> [--product p] (Business; --ref and --purpose keep only its runs of one record or purpose): acceptance and signing state, criteria as walked with requirement references, results, screenshot hashes, decisions, signatures, audit trail; --csv prints the trace matrix, --json the whole document
kaloko video exportTurns the run's recordings into one video; kaloko video list, trace and tools show recordings, traces and tools
kaloko screensSearches the newest screenshot of every step across your flows
kaloko inboxYour notifications on kaloko.app

Shared runs

CommandWhat it does
kaloko projectsProjects of the organization
kaloko projects create <slug>Creates a project with the name people see (--name "ECO Podcasty"), optionally restricted or part of a product; an existing project is refused, not renamed
kaloko projects rename <slug>Changes the name people see; the project's admin does this
kaloko projects syncMakes Kaloko match project:, project_name: and product: of the config: creates the project when it is missing, renames it when the name differs, adds it to the product
kaloko runsShared runs, the newest per scenario; --all lists every run, page by page to the last; --limit N stops after N and --cursor goes on from there; --ref CC-2026-001 lists every run of that record, --purpose formal only the formal runs
kaloko trash <run-id…>Moves runs to the trash; kaloko restore <run-id> brings one back
kaloko pruneKeeps the newest runs per scenario and environment and lists the rest for the trash; --yes moves them
kaloko keep <run-id>A kept run never expires and is never pruned; --off releases it
kaloko archive <scenario-id>Hides a retired scenario from the list; its runs stay
kaloko scenario move <scenario-id> --project <slug>Moves a scenario to another existing project with all its runs, design drafts and screens, like Scenario settings on the scenario's page in the app. The move wins over project: in the config and the scenario file: later shares of the scenario land in the new project too, until you move it back
kaloko publicMakes a shared run readable without signing in
kaloko export run|stepsrun downloads a shared run as a zip; steps --scenario <id> the newest capture of every step (the flags --run and --scenario still work)
kaloko export findingsThe fix list of a local run: every failing criterion and health check per page and language with its evidence, the page's edit_url and content_ref and the walk that checks it again; with traffic in the config also the page's clicks, impressions and sessions and an impact, highest first; --format csv|json, --locale, --step, --out

Jira, Linear and hosted runs

CommandWhat it does
kaloko issue createAn issue in Jira or Linear from a returned step or a failing criterion; kaloko issue list shows them
kaloko schedule addKaloko opens the pages of a read-only scenario every day or week and shares the run; --health-alert error|warning|off says when worse health alerts the team
kaloko schedule list|run|pause|resume|removeManages the schedules
kaloko schedule hook <id> [--remove]A URL and secret that start the hosted run after a deploy or from CI; the secret is shown once
kaloko schedule export githubA GitHub Actions workflow that walks the scenario on a schedule with the full CLI

Products, changelog and docs

CommandWhat it does
kaloko products syncPuts the products of the config on Kaloko without recording a release
kaloko products listThe products you read on Kaloko, and those of the config that are not there yet
kaloko products remove <product>Archives a product: it leaves Products, its changelog and docs answer 404, its releases and docs are kept
kaloko products restore <product>Brings an archived product back with its releases and docs
kaloko changelog draftWrites the Unreleased entry from merged pull requests and changed screens; --apply writes it into CHANGELOG.md
kaloko release [<version>]Records a release with its changelog entry, pictures and docs
kaloko docs publishSends the docs folder to Kaloko as the docs of a version
kaloko docs checkBroken references, stale sections, missing translations and changelog items without a picture; exits 1 on errors
kaloko export docsThe docs and changelog as Markdown (the default), Docusaurus, VitePress, MkDocs, HTML, PDF or JSON with --format; kaloko export --format <f> still works

Design

CommandWhat it does
kaloko syncExchanges design revisions with the shared draft (--pull, --push)
kaloko design lintChecks the design folder against the portable HTML rules
kaloko design import figmaTurns Figma frames into design steps and variables into tokens
kaloko historyVersions of the flow and revisions of a step
kaloko spec [step]What to build for an approved design step: elements, styles mapped to tokens, states; --state empty for one step state
kaloko drift [step]How the implementation differs from the approved design; exits 1 while it differs
kaloko referenceShows or sets the design reference and the baseline
kaloko tokens pull|push|check|validateThe project's design tokens (DTCG)
kaloko branch list|create|mergeBranches of the design draft
kaloko export live|designlive the live files of a version into a folder (the handoff), design a version in open formats; --live and --design still work

Machine output

With --json, a command that prints data writes one JSON document to stdout and nothing else; progress, notes and warnings go to stderr. It works on start, status, evaluate, build, share, validate, scenarios, runs, projects, review, feedback, inbox, auth list, browser status, ci preview-url, affected, prune, devices, doctor and the other commands whose help names it. kaloko share --json prints the run id and its URL:

url=$(npx kaloko share --json | jq -r .url)

When a command fails with --json, stderr ends with one line like {"error":{"message":"Cannot reach https://kaloko.app (ENOTFOUND).","code":"unreachable","next":"…"}}. code is usage, unreachable, no_token, unauthorized, failed or the service's own reason (such as plan).

Commands from a newer kaloko

kaloko help --json prints every command with its sub-commands and options as JSON ({"version":"…","commands":{"<name>":{"flags":[…],"subcommands":{…}}}}); an agent can read it instead of the help text.

When you type a command, sub-command or option this kaloko does not know, it looks at /cli/latest.json on the service it talks to (kaloko.app, or KALOKO_URL): the commands of the newest released kaloko, kept for a day in ~/.cache/kaloko. Only when that version is newer than yours and has exactly what you typed, it says so instead of guessing a typo:

There is no command "projects" in this kaloko.
kaloko projects is in kaloko 0.16.0 (you have 0.15.0). Update: npm i -D kaloko@latest

The exit code stays 2, and with --json the line is the error's next. Offline it waits at most 1.5 s and prints what it printed before. KALOKO_NO_UPDATE_CHECK=1 or --offline turns the check off. kaloko doctor also says when a newer kaloko is available.

Exit codes

CodeMeaning
0Done
1Checks found problems, or the command failed (docs check, drift, design lint, affected --fail-if-none and validate use 1 for their findings)
2Usage error: an unknown command or option, a missing argument
3The Kaloko service cannot be reached: offline, DNS, a refused or broken connection. An error answer from the service is 1
4No token, or one that is invalid, expired or revoked: run kaloko login

Durations

--timeout (mail), --wait (ci preview-url), --expires (share) and --older-than (prune) take a number in their own unit, as before (seconds for the first two, days for the others), or a number with s, m, h or d: --wait 10m, --expires 72h, --older-than 14d.

kaloko help prints all of this with every option.

Kaloko · latest · 2026-11-21