CLI overview
Global options, exit codes and the full command map of the sdods command.
How the sdods command is organised, which global options every command accepts, what the exit
codes mean, and where each command group is documented.
Invocation
Inside the repository the command runs from source:
bun run sdods <command> [options]After publishing, npx -y @sdods/cli <command> or a global install do the same.
Global options
| Option | Effect |
|---|---|
--json | machine-readable output; errors become { "error": { code, message, hint, docsUrl } } on stderr |
-q, --quiet | errors only |
--verbose | debug logging |
--cwd <dir> | repository root; by default SDODS walks up from the current directory to find sdods.workspace.yaml, sdods.config.ts or a projects/ folder |
--no-color | disable colours |
-V, --version | print the version |
Some flags have an SDODS_* environment equivalent (workers, retries, shard, headed, base URLs, screenshot policy, HAR mode and others); Environment variables lists them. Flags such as --grep, --feature and --max-failures have none.
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | test failures, or a runtime error |
2 | configuration or usage error (unknown project, missing environment, invalid YAML, unresolved variable) |
3 | lint errors |
130 | cancelled |
Common workflows
The commands in the order a project usually meets them. Each block assumes the one above it.
Every command supports --json, --quiet, --verbose, --cwd and --no-color;
sdods <command> --help prints the full option list.
1. Start a new project
In order. Each step assumes the one above it.
sdods init ~/my-tests # workspace yaml, runner config, demo project, skills
cd ~/my-tests
sdods doctor # Node, bun, browsers, projects, env vars, database
sdods browsers install -b chromium # engines are a separate download; every layer, API included, launches one
sdods project create checkout # a project is one app under test
sdods env add staging -p checkout --ui-url https://staging.example.com --api-url https://api.staging.example.com
sdods config show -p checkout -e staging --explain # what resolved, and which file won2. Onboard an application you already have
analyze reads a repository and proposes a project from what it finds — routes, API endpoints, test-id attributes. It is read-only until you pass --apply.
sdods analyze /path/to/your-app # propose, change nothing
sdods analyze /path/to/your-app --apply # write the project
sdods steps list -p <slug> # the vocabulary you can write with
sdods coverage -p <slug> # routes, endpoints and roles with no scenarios yet3. Write, check, run
The inner loop. lint before run — it is far cheaper and catches tag and step mistakes.
sdods lint -p <slug> # Gherkin, tag taxonomy, undefined steps
sdods run -p <slug> -e staging --list # what would run, without running it
sdods run -p <slug> -e staging -l api # API layer, no browser
sdods run -p <slug> -e staging -l ui -b chromium -t @smoke # UI smoke
sdods run -p <slug> -e staging -t @regression --project-matrix # every browser in the yaml
sdods watch -p <slug> -e staging # regenerate and re-run on change4. Read the results
sdods report --last # totals, failures, flaky, artifact paths
sdods report --last --open # HTML report and dashboard
sdods trace --last # Playwright trace viewer
sdods show-report --last # just the HTML report5. Heal, and learn from history
heal reports locators that drifted and were recovered at runtime; insights aggregates across runs so you fix causes rather than symptoms.
sdods heal report --last # locators healed in the last run
sdods heal report --all # aggregate every run: what keeps drifting
sdods heal report --last --write-history # bias future heals toward what worked
sdods insights compute -p <slug> # crunch the run history
sdods insights show -p <slug> # flakiness, locator fragility, suite health
sdods agent heal -p <slug> --scenario <fingerprint> --dry-run # propose the smallest fix6. Record and replay
sdods record -p <slug> -e staging --user admin --name checkout-flow # capture a session
sdods har record -p <slug> -e staging # capture network
sdods har replay --strict # run offline against the capture
sdods auth capture -p <slug> -e staging --user admin # store login state for a pool user7. Data and database
sdods data import users users.csv -p <slug> # <dataset> <file>: CSV, JSON or YAML
sdods data preview users.csv # first rows, as the runner will see them
sdods data list -p <slug>
sdods data seed -p <slug> -e staging
sdods db migrate # platform database
sdods db status
sdods db sync # upsert orgs, workspaces, projects from the yaml
sdods db switch postgres # SQLite <-> Postgres (target is positional)8. The web UI and the platform
sdods users create --admin --username admin --password '<8+ chars>'
sdods serve --open # http://127.0.0.1:4444
sdods tokens create --scopes run:read,run:write # free, scoped, revocable
sdods schedule add -p <slug> --name nightly --cron '0 3 * * *' -t @regression
sdods integrations test githubFirst run with no users prints a one-time /setup?token=… URL; open it to create the admin in the browser instead. Full detail, including every OS: the web UI guide.
9. Agents and MCP
Agents never edit your working tree — they write proposals a person accepts.
sdods agent plan|generate|heal|upgrade|review -p <slug> --dry-run
sdods proposals list
sdods proposals show <id>
sdods proposals accept <id> # or reject
sdods mcp install claude|codex|copilot|cursor|vscode|windsurf
sdods mcp --http --port 4001 # streamable HTTP with scoped tokens10. Keep it current
upgrade checks the npm registry for newer @sdods/* packages and, with --apply, installs them with whichever package manager your lockfile implies.
sdods upgrade # report what is behind
sdods upgrade --apply # install the latest @sdods/* packages
sdods browsers install --with-deps # refresh engines after an upgrade (Linux needs root)
sdods doctor # confirm the resultCommand map
| Group | Commands | Status |
|---|---|---|
| Onboarding | init, analyze, project, env, config, doctor | project, env, config, doctor available |
| Authoring and execution | run / test / watch, lint, steps, features, coverage, browsers, processes, load | Phases 1–2, 12 |
| Record and playback | record / codegen, har, auth | Phases 3, 6 |
| Data and database | data, db | Phase 5 |
| Results and learning | report, show-report, trace, heal, insights, baselines | Phases 2, 5, 8 |
| Agents | agent, proposals | Phase 8 |
| Platform | mcp, serve, users, tokens, schedule, integrations, completion, upgrade | Phases 7, 9, 11 |
Run bun run sdods --help or bun run sdods <command> --help for the live surface.
bun run sdods --help