> For the complete documentation index, see [llms.txt](https://docs.testvibe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testvibe.com/testvibe-api/cli/cli.md).

# The testvibe CLI

The `testvibe` npm package wraps the [REST API](/testvibe-api/api-reference/reference.md) for your terminal, and doubles as the [MCP server](/testvibe-api/mcp-server/mcp.md) (`testvibe mcp`). It's a single bundled file with zero runtime dependencies — all it needs is **Node 20+**.

```bash
npm install -g @testvibe/cli   # not yet on npm? install from the repo: npm i -g <repo>/cli
```

## 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]`                       | Generate Playwright tests from the feature's Gherkin. `--watch` polls progress.                                                             |
| `testvibe run <feature>\|--all [--config Name] [--url https://…] [--wait]`      | 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]`     | List runs, show one's results, get a failed run's full failure context, or get artifact download links.                                     |
| `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 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` | 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" }`.                                                                  |

{% hint style="info" %}
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](/testvibe-api/guides/run-in-ci.md).
{% endhint %}

## Exit codes & output

Commands print human-readable output and exit non-zero on failure (API errors surface the server's `message` verbatim) — `run --wait` exits non-zero when any run fails, which is exactly what a CI gate wants. `run --all --wait` waits on every dispatched run and prints a suite summary.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/testvibe-api/cli/cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.