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
| Command | What it does |
|---|---|
kaloko init | Creates 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 login | Signs this machine in through the browser and saves a token (at most 30 days) to ~/.config/kaloko/.env; --print prints it instead |
kaloko doctor | Checks 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 scenarios | Lists the scenarios the config matches |
kaloko ci github|gitlab | Writes a workflow that walks what each pull request affects on its preview deployment and comments on it |
kaloko ci github --release | Writes a workflow that records every release your release tool publishes |
kaloko ci preview-url | In CI: finds the preview URL, the pull request and its base |
kaloko ci plan | In CI or a coding agent's sandbox: tells the Kaloko check on the pull request which scenarios this commit reaches |
Walk and capture
| Command | What it does |
|---|---|
kaloko start | Creates 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 walk | Runs 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|status | One shared browser per environment that agents, scripts and people drive |
kaloko browser install | Downloads the browser engines (--browsers chromium,webkit,firefox) |
kaloko devices | Lists the device presets you can use as viewports |
kaloko session reset | Starts as a new visitor: clears cookies and storage in the shared browser |
kaloko auth save | A person signs in once (SSO, MFA) and the walk reuses the session; kaloko auth list shows saved sessions |
kaloko affected | Says 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 status | Shows what the current run has captured |
Results and review
| Command | What it does |
|---|---|
kaloko evaluate | Runs 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 build | Writes run.json and the local preview |
kaloko preview | Builds the preview and prints its path |
kaloko share | Uploads 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 review | What a person still has to decide on a shared run, and the review-mode link |
kaloko health | The 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 pull | Writes the checks people adopted on kaloko.app into the scenario file |
kaloko feedback | Open comments from reviewers, returned steps first |
kaloko comment | Comments, replies, resolves and reopens feedback from the terminal |
kaloko compare | A text diff of two runs: statuses, verdicts, scores and evidence |
kaloko stability | Finds regions that change on every run; --apply adds them to the scenario, --pull brings in regions drawn on kaloko.app |
kaloko calibrate | Compares 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 export | Turns the run's recordings into one video; kaloko video list, trace and tools show recordings, traces and tools |
kaloko screens | Searches the newest screenshot of every step across your flows |
kaloko inbox | Your notifications on kaloko.app |
Shared runs
| Command | What it does |
|---|---|
kaloko projects | Projects 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 sync | Makes 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 runs | Shared 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 prune | Keeps 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 public | Makes a shared run readable without signing in |
kaloko export run|steps | run 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 findings | The 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
| Command | What it does |
|---|---|
kaloko issue create | An issue in Jira or Linear from a returned step or a failing criterion; kaloko issue list shows them |
kaloko schedule add | Kaloko 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|remove | Manages 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 github | A GitHub Actions workflow that walks the scenario on a schedule with the full CLI |
Products, changelog and docs
| Command | What it does |
|---|---|
kaloko products sync | Puts the products of the config on Kaloko without recording a release |
kaloko products list | The 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 draft | Writes 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 publish | Sends the docs folder to Kaloko as the docs of a version |
kaloko docs check | Broken references, stale sections, missing translations and changelog items without a picture; exits 1 on errors |
kaloko export docs | The docs and changelog as Markdown (the default), Docusaurus, VitePress, MkDocs, HTML, PDF or JSON with --format; kaloko export --format <f> still works |
Design
| Command | What it does |
|---|---|
kaloko sync | Exchanges design revisions with the shared draft (--pull, --push) |
kaloko design lint | Checks the design folder against the portable HTML rules |
kaloko design import figma | Turns Figma frames into design steps and variables into tokens |
kaloko history | Versions 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 reference | Shows or sets the design reference and the baseline |
kaloko tokens pull|push|check|validate | The project's design tokens (DTCG) |
kaloko branch list|create|merge | Branches of the design draft |
kaloko export live|design | live 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
| Code | Meaning |
|---|---|
0 | Done |
1 | Checks found problems, or the command failed (docs check, drift, design lint, affected --fail-if-none and validate use 1 for their findings) |
2 | Usage error: an unknown command or option, a missing argument |
3 | The Kaloko service cannot be reached: offline, DNS, a refused or broken connection. An error answer from the service is 1 |
4 | No 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.