CLI Reference
Command-line reference for npx donobu test, its Donobu-specific flags, and the other donobu commands: init, heal, cache, cases, explore, context, runs, results, session, and skills.
The Donobu CLI wraps Playwright's own CLI, forwarding all standard Playwright arguments while adding Donobu-specific flags and subcommands.
Running tests
npx donobu test [playwright-args] [donobu-flags]
The test subcommand is optional — npx donobu [flags] is equivalent to npx donobu test [flags].
Every argument supported by npx playwright test is also supported here. Common examples:
# Run all tests
npx donobu test
# Run a specific test file
npx donobu test tests/checkout.test.ts
# Run tests matching a pattern
npx donobu test --grep "login"
# Run in headed mode
npx donobu test --headed
# Run with a specific Playwright project
npx donobu test --project=chromium
Refer to the Playwright CLI documentation for the full list of supported arguments.
Donobu-specific flags
These flags are consumed by Donobu before the remaining arguments are forwarded to Playwright.
--auto-heal
Enables automatic test healing. When a test fails, Donobu collects failure evidence and hands the failures to the heal agent. The agent fixes test-side causes, Donobu re-runs the affected tests to verify the fix, and in GitHub Actions or GitLab CI the verified fix is published as one pull request. Without agent access, Donobu falls back to the classic path: it clears the cache and re-runs failures diagnosed as stale cached steps.
npx donobu test --auto-heal
See Self-Healing Tests for full details.
--clear-ai-cache
Invalidates the Page.AI cache for all page.ai() calls in the run. Forces the AI to re-execute every flow from scratch rather than replaying cached action sequences.
npx donobu test --clear-ai-cache
Useful when you want to verify that the AI can still complete all flows against the current state of the application.
--no-triage
Disables failure evidence collection. By default, Donobu captures screenshots, DOM snapshots, and AI-generated triage analyses when tests fail. Passing --no-triage skips this step, which can speed up runs where you know the failures are expected or irrelevant.
npx donobu test --no-triage
--triage-output-dir <path>
Overrides the directory where failure evidence and treatment plans are written. Defaults to <playwright-output-dir>/donobu-triage.
npx donobu test --triage-output-dir ./my-triage-output
# or
npx donobu test --triage-output-dir=./my-triage-output
The heal subcommand
npx donobu heal applies a previously generated treatment plan to attempt to repair a specific failing test without running the full test suite.
npx donobu heal --plan <path-to-plan.json> [-- playwright-args]
Arguments
| Argument | Description |
|---|---|
--plan <path> (required) | Path to the treatment plan JSON file generated during a previous triage run. The plan path can also be passed as a positional argument. |
--triage-output-dir <path> | Override the output directory for triage artifacts produced during the heal run |
-- [playwright-args] | Arguments after -- are forwarded directly to Playwright |
Example
# Apply a specific treatment plan
npx donobu heal --plan test-results/donobu-triage/treatment-plan-*.json
# Pass additional Playwright arguments
npx donobu heal --plan ./plan.json -- --headed --timeout=60000
Treatment plans are generated automatically in the triage output directory when tests fail and --no-triage is not set. Use --auto-heal during a normal test run to apply them automatically rather than running donobu heal manually.
Setting up a project: donobu init
npx donobu@latest init sets up a project for Donobu in one step. See Installation & Setup for what it does.
npx donobu@latest init
Use @latest here: a bare npx donobu may reuse an older cached copy. After init installs @donobu/test, npx donobu runs the installed CLI.
Checking your setup: donobu status
Shows the Donobu account behind your API key.
npx donobu status [--json]
Hosted AI cache: donobu cache
Works with the hosted copy of the page.ai() cache. See Caching System.
npx donobu cache status [--json] # Is the hosted cache active for this account?
npx donobu cache push [dir] # Upload committed assert and locate entries
npx donobu cache show <hash> [--json]
Test cases: donobu cases
Manages your test-case inventory in Donobu Cloud. Requires DONOBU_API_KEY. A case is named by its UUID or its exact slug.
npx donobu cases list [--section <s>] [--priority <p[,p...]>] [--app <origin>] [-n <count>] [--json]
npx donobu cases show <case> [--json]
npx donobu cases create <slug> --title <title> [--description <text>] [--section <s>] [--priority low|medium|high|critical]
npx donobu cases update <case> [--title <title>] [--priority <p>] ...
npx donobu cases accept <proposal-id> # Accept one of Donobu's proposed test cases
npx donobu cases link <case> <test-id>
npx donobu cases unlink <case> <test-id>
npx donobu cases delete <case-uuid>
delete takes a UUID only, because it cannot be undone. Linked tests are not deleted.
Exploring an app: donobu explore and donobu context
donobu explore runs the same autonomous, read-only exploration as the Explore button in Donobu Studio. It then adds what it saw to the app's knowledge base.
npx donobu explore <url> [--focus "<what to look for>"] [--headless] [--max-tool-calls <n>] [--env NAME] [--timeout-minutes <n>] [--json]
--env NAME lets the run use an environment variable from the project .env, for example a login. Repeat it for more than one variable.
donobu context reads the knowledge base:
npx donobu context list # Apps with fact, page, and anomaly counts
npx donobu context show [origin-or-app-id] [--json] # One app's knowledge base
npx donobu context proposals [origin-or-app-id] [--json] # Proposed test cases
npx donobu context export [origin-or-app-id] [--dir <path>]
npx donobu context ask "<question>" [origin-or-app-id] [--json]
context ask answers a question about the app from what Donobu has learned, with citations. It needs an AI provider key.
Runs and results: donobu runs and donobu results
npx donobu runs list [-n <count>] [--json]
npx donobu runs show <run | latest> [--json]
npx donobu results list [--test "<title>"] [--run <run>] [-n <count>] [--json]
npx donobu results show <result-id> [--json]
Name a run by its ID, a unique ID prefix, or the CI run it came from. You can paste the CI run URL directly:
npx donobu runs show https://github.com/acme/shop/actions/runs/123456789
Live browser sessions: donobu session
donobu session starts a browser that you or a coding agent can drive one command at a time. Every command prints JSON.
npx donobu session start [--url <url>] [--headless] [--env NAME]
npx donobu observe
npx donobu click --element 12
npx donobu save tests/checkout.test.ts # Save the steps as a test
npx donobu session list
npx donobu session end
The installed agent skill teaches coding agents the full set of session commands.
Agent skills: donobu skills
Installs the Donobu skill for coding agents such as Claude Code and Codex.
npx donobu skills install [--dir <path>] [--force]
npx donobu skills status [--dir <path>] [--check]
install writes the skill to .claude/skills/donobu and .agents/skills/donobu, and adds a managed block to AGENTS.md. It also installs skills from any installed Donobu plugins. status --check exits with a non-zero code when the installed skill differs from the packaged one.
Logging
By default, Donobu prints additional output alongside Playwright's normal output. To suppress it:
LOG_LEVEL=error npx donobu test