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

# CLI

Use the DoesQA CLI (doesqa) so an AI coding agent or a person can author, run, and mirror Tests from the terminal.

The DoesQA **CLI** (`doesqa`) is the same bridge as [MCP](/doesqa-ai/doesqa-ai/mcp.md), with a terminal on the front. An AI coding agent (or a person) authenticates with an [access token](/doesqa-ai/doesqa-ai/access-tokens.md), then authors Flows, starts Runs, reads Results, asks the Assistant, and keeps a local [DoesQA Sync](#doesqa-sync) mirror.

Install and run commands on Node.js 18 or newer:

```bash
npm install -g doesqa
doesqa whoami
```

The [Flow Builder](/platform/flow-builder.md) stays the primary way people author Tests. The CLI is how an agent (or a terminal workflow) joins in.

## Connect

{% stepper %}
{% step %}

## Create an access token

Go to **Settings → User** and create a token under **Access Tokens**. Copy it once. Full steps: [Access tokens](/doesqa-ai/doesqa-ai/access-tokens.md).
{% endstep %}

{% step %}

## Log in from the terminal

Run this in a local terminal, then paste the token when asked. The prompt hides what you type.

```bash
doesqa login
```

In a secure local shell you can pass the token on the command line instead:

```bash
doesqa login --token 'paste-the-token-here'
```

Keep the token out of chat, and keep it out of source control.
{% endstep %}

{% step %}

## Confirm the connection

```bash
doesqa whoami
doesqa health
```

{% endstep %}
{% endstepper %}

The account comes from the token. To switch accounts, run `doesqa logout`, then log in with a token from the other account.

Auth controls (your user, duration, and delete) are the same as MCP. See [Control agent access](/doesqa-ai/doesqa-ai/mcp.md#control-agent-access) and [Security](/platform/security.md#agent-access-mcp-and-cli).

## What you can do

Every command runs against the authorised account. Add `--json` for structured output and `--out <file>` to save large results to disk. Run `doesqa help --json` for the full, current command tree.

Common groups include:

| Area             | Examples                                                            |
| ---------------- | ------------------------------------------------------------------- |
| Flows and steps  | `doesqa flows create`, `doesqa flows show`, `doesqa flows add-node` |
| Elements         | `doesqa elements create`, `doesqa elements list`                    |
| Runs and results | `doesqa runs start`, `doesqa runs watch`, `doesqa tests summary`    |
| Assistant        | `doesqa ask "How is login covered?"`                                |
| Memory           | `doesqa memory recall`, `doesqa memory remember`                    |
| Mirror           | `doesqa init`, `doesqa pull`, `doesqa status`                       |

Capability detail matches [MCP](/doesqa-ai/doesqa-ai/mcp.md#what-the-agent-can-do). Prefer `doesqa flows show` when you want a Flow as a Mermaid diagram and step map. Prefer `doesqa ask` when you need the in-app Assistant instead of guessing about the account.

{% hint style="info" %}
**Pro tip:** Seed a project with `doesqa init`. It writes `.doesqa/AGENT.md`, a starter prompt that teaches an agent what it can do with this CLI.
{% endhint %}

## Review agent work

Change and Run commands return a `reviewUrl` deep into the app (a Flow, a Test Case, or a Run). Always open that link and review the journey in DoesQA. Assistant exchanges are visible conversations in the app as well.

See [Review agent work](/doesqa-ai/doesqa-ai/mcp.md#review-agent-work).

## Memory for agents

Memory scopes and rules are shared with MCP. Default scope is **user** (private to the person behind the token). Pass account scope when a fact should be recalled by the whole team’s agents. Never store secrets.

Full table: [Memory for agents](/doesqa-ai/doesqa-ai/mcp.md#memory-for-agents).

## DoesQA Sync

DoesQA Sync is the read-only local mirror of your Flows, Elements, and Run Recipes.

```bash
doesqa init    # seed .doesqa/ including AGENT.md
doesqa pull    # refresh the mirror from the live account
doesqa status  # show how the local mirror differs from the platform
```

What lands under `.doesqa/`:

| Path                                | Contents                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `.doesqa/flows/<slug>-<id>.flow.md` | Front matter, Mermaid diagram, JSON step map (same document as `doesqa flows show`) |
| `.doesqa/elements/*.element.json`   | Flat Element records                                                                |
| `.doesqa/recipes/*.recipe.json`     | Flat Run Recipe records                                                             |
| `.doesqa/AGENT.md`                  | Starter agent prompt from `doesqa init`                                             |

Output is deterministic, so committing `.doesqa/` gives reviewable diffs. A changed Test Step shows up as a changed line in the diagram and in the step map.

Treat these files as reference. Edit Tests with CLI commands, MCP tools, or the app, not by editing the mirror by hand.

## Related

* [Access tokens](/doesqa-ai/doesqa-ai/access-tokens.md)
* [MCP](/doesqa-ai/doesqa-ai/mcp.md)
* [DoesQA AI](/doesqa-ai/doesqa-ai.md)
* [Platform → DoesQA AI](/platform/doesqa-ai.md)
* [Security](/platform/security.md#agent-access-mcp-and-cli)
* [Flow Builder](/platform/flow-builder.md)
* [Runs](/runs/runs.md)
* [Integrations](/platform/integrations.md)