The testvibe CLI
The testvibe npm package wraps the REST API for your terminal, and doubles as the MCP server (testvibe mcp). It's a single bundled file with zero runtime dependencies — all it needs is Node 20+.
Install
Pick whichever fits your setup. Every method installs the same dependency-free bundle and only needs Node 20+ already on your machine.
- npm
- macOS / Linux (no npm)
- Windows (no npm)
npm install -g testvibe
Installs the testvibe package from the public npm registry.
Download and install straight from your TestVibe server — no npm needed:
curl -fsSL https://testvibe.app/api/v1/install.sh | sh
It drops a testvibe command in ~/.testvibe/bin (override with TESTVIBE_PREFIX) and prints a line to add it to your PATH. Swap in your own host if you're self-hosting.
From PowerShell:
iwr -useb https://testvibe.app/api/v1/install.ps1 | iex
It installs testvibe into %USERPROFILE%\.testvibe\bin and prints a setx PATH line to add it. Swap in your own host if you're self-hosting.
The curl | sh and iwr | iex installers download a single file (testvibe.mjs) from /api/v1/cli/testvibe.mjs on your TestVibe server and add a testvibe shim that runs it with node. No npm registry, no build step — just Node 20+.
Then log in once per machine:
testvibe login --server https://testvibe.app --key tvb_XXXXXXXX…
testvibe use <project>
Commands
| Command | What it does |
|---|---|
testvibe login [--key tvb_…] [--server https://…] | Store an API key for this machine. Verifies the key before saving. |
testvibe logout | Remove the stored API key. |
testvibe whoami | Show the configured server, key prefix, and default project. |
testvibe use <project> | Set the default project (by public id or name). |
testvibe projects | List the projects in your workspace. |
testvibe project [id] | Show one project's details (base URL, execution target, test site URLs). |
testvibe features [list|show|create|update|delete] … [--status generated] | Manage features (create <name> --file <path> or --gherkin '…'). |
testvibe generate <feature> [--url https://…] [--watch] [--timeout <seconds>] | Generate Playwright tests from the feature's Gherkin. --watch polls progress until the generation finishes — see the wait contract. |
testvibe run <feature>|--all [--config Name] [--url https://…] [--wait] [--timeout <seconds>] | Run a feature's tests in a cloud sandbox — or every generated feature with --all (one run per feature). --wait prints per-test results. |
testvibe runs [list|show|diagnose|artifacts] [runId] [--status failed] [--links] | List runs, show one's results, get a failed run's full failure context, or get artifact download links. artifacts is the subcommand that issues signed download URLs; diagnose prints artifact paths only — add --links there when you do want the URLs. |
testvibe verify [--files f1 f2 …] [--git [ref]] [--all] [--url https://…] [--wait] [--timeout <seconds>] | Verify a code change: TestVibe maps the files you edited to the tests that cover them and runs exactly those. --git [ref] collects the changed files for you. --wait prints a per-feature verdict table. |
testvibe files [list|get|put|delete] … | List, print, write, or delete project files (writes/deletes only under Features/ or Configurations/). |
testvibe configs | List the Playwright configurations available to runs. |
testvibe load [list|create|update|delete|run] [loadTest] [--name …] [--mode simple|advanced] [--features id1,id2] [--paths /,/x] [--vus N] [--duration S] [--ramp S] [--repeats N] [--thresholds "http_req_duration:p(95)<1000"] [--url https://…] [--wait] [--timeout <seconds>] | List, create, edit, delete, or dispatch load tests. Simple mode replays functional features (--features); advanced drives k6 against paths (--paths). --wait polls a dispatched run until it finishes. |
testvibe telemetry [live|errors|metrics] [runId] [--status open] [--limit 50] | Read telemetry: live streaming server vitals (Live Servers), errors fingerprinted application-error groups, metrics <runId> a load run's persisted server samples. Read-only. |
testvibe automations [list|show|create|update|delete|run|runs] … | Manage automations (schedule/event triggers → run features or a load test), fire one now, or view firing history. |
testvibe coverage [show|scan|runs|run] [--target id] [--wait] [--timeout <seconds>] | Show the coverage snapshot, trigger an AI area scan, list execution-coverage runs, or start one. --wait polls to completion. |
testvibe plugins [list|install|remove|publish|unpublish] … [--installed] | Manage the project's plugin catalog — list it, enable/disable a plugin, or publish/unpublish a workspace package (publish --name "My Plugin" [--file source.js]). |
testvibe vars [list|set|delete] [NAME] [value] | List, set, or delete project variables (plaintext, injected into runs and generation). |
testvibe secrets [list|set|delete] [NAME] [value] | List, set, or delete project secrets. list shows names only — values are write-only. |
testvibe mcp | Start the MCP stdio server. |
Configuration
Settings resolve in priority order — first hit wins:
| Priority | Source | Holds |
|---|---|---|
| 1 | Environment: TESTVIBE_API_KEY, TESTVIBE_SERVER, TESTVIBE_PROJECT, TESTVIBE_WAIT_TIMEOUT_SECONDS | Anything — ideal for CI. |
| 2 | Per-repo .testvibe.json | { "server": "…", "project": "…" } — commit it so a repo is pinned to its project. No keys here. |
| 3 | ~/.testvibe/config.json (written by testvibe login) | { "server", "apiKey", "project" }. |
A typical setup: testvibe login once per machine, a committed .testvibe.json per repo pointing at its project, and env vars in CI. See Run TestVibe in CI.
Waiting, and what the exit code means
--wait (--watch on generate) polls until the work reaches a terminal state. A run is still in flight in queued, allocating and running — none of those is an outcome, and none of them is a failure.
| Exit code | Meaning |
|---|---|
0 | Everything finished and passed / succeeded. |
1 | It finished and something actually failed. |
2 | A generation parked to ask you a question — it needs a human, nothing is broken. |
3 | We stopped waiting: the --timeout ceiling elapsed, or we lost contact with the server. No verdict — the work may still be running, and this never means your tests failed. |
Anything the command rejects outright (a bad flag, an API error — the server's message is surfaced verbatim) is also 1.
--timeout <seconds>
--timeout <seconds> caps how long a --wait/--watch polls, as one budget for the whole command (a suite of 19 runs still waits at most this long in total, not 19×). It defaults to 5400 s and can be set with TESTVIBE_WAIT_TIMEOUT_SECONDS; --timeout 0 waits indefinitely.
testvibe run --all --wait --timeout 900 # give the whole suite 15 minutes
TESTVIBE_WAIT_TIMEOUT_SECONDS=900 testvibe run --all --wait # same ceiling, from the environment
testvibe generate "Login Functionality" --watch --timeout 0 # no ceiling at all
It applies to run, verify, load run, coverage scan, coverage run, and generate --watch. A malformed value is refused before anything is dispatched, so a typo never costs credits.
Exit 3 is not a test failure. The remedy is "look at the run" or "raise --timeout", never "fix your code" — see Run TestVibe in CI for wiring that into a pipeline.
Commands that wait on several runs
run --all --wait, run <a> <b> --wait and verify --wait wait on every run they dispatched and print a summary. A run they stopped watching is tabulated as no verdict, not as a failure: the summary exits 1 if anything actually failed, and 3 only if nothing failed but something was still unfinished.
Cloud API, CLI, and MCP access requires Team or higher. See authentication and access limits.
Additional current commands
| Command | Purpose |
|---|---|
testvibe models | Discover current model ids, provider configuration, and the project default. |
testvibe generate <feature> --model <id> | Choose a model for one generation; --model auto selects from the current catalog. |
testvibe generate log <feature> --json | Read the full latest transcript, including section logs. |
testvibe generate answer <feature> --option "…" --watch | Answer a pending question and follow resumed work; also accepts --message or --fields. |
testvibe groups list|create|rename|delete | Manage test folders; deletion ungroups their features. |
testvibe features history <feature> --diff | Inspect revisions and changed lines. |
testvibe features list --group <name> | Filter by group, optionally with --status. |
testvibe issues --state open | List linked GitHub issues; features import-issue <number> starts a draft import. |
testvibe clone <source> --to <project> | Copy feature sources/groups as drafts; optional --loadTests --memories --variables. No secrets, generated code, or runs are copied. |
testvibe source-repo show|set|options|disconnect | Manage the source repository used by coverage. |
testvibe load results <runId> --json | Read load measurements and threshold verdicts; --samples includes the series. |
testvibe runs trace <runId> | Read trace analysis; --path selects a trace artifact. |
testvibe assets list --folder <path> | Inspect assets and stable handles; assets delete <id-or-path> removes one. |
testvibe credits usage --by-member | Show who consumed credits. |
testvibe assistant "<prompt>" | Run a project Assistant turn (metered). |
Use testvibe --help and testvibe --version to inspect the installed CLI. Global --project <id> and --server <url> override configured defaults. --json is command-dependent; the current generation dispatch uses human-readable output even with that flag.
generate <feature> --watch starts a new generation. It is not a way to attach to an already running generation. Use REST/MCP status reads for that, or generate answer … --watch to continue a paused question. API dispatches are silent by default; --notify opts into completion notifications.