# Use Testlane from an Agent

> Let an AI coding agent check out a ref, start a preview, read its logs, stop it and clean up, with the commands, JSON fields and exit codes it needs.

An AI coding agent can review a pull request the way you do: check it out, start it, open the URL, read the logs, then stop it and clean up. It needs to know which commands to call and which fields to read, though. Without that, an agent guesses. Think of an agent that calls `shell` and waits forever for someone to type, one that runs a dev server with `run` and never gets its prompt back, or one that parses the progress lines on stderr instead of the JSON on stdout.

By the end of this guide, your agent can drive the whole loop on its own, and you'll know what it reads at each step.

## Before you start

You'll need Testlane installed, at least one project configured and your agent connected, which [Agents](https://testlane.dev/docs/getting-started/agents) covers. The examples use a project called `my-project` with a `dev` command, and show real output. Your paths, ports and PIDs will differ. Testlane prints each JSON result on one line, and we've wrapped them here so they're easier to read.

Every step below also relies on three rules:

- **Pass `--json`, and read data from stdout only.** Progress (`→ …`), warnings and errors always go to stderr. The output of the project's `[setup]` and hooks goes to stdout as well, unless you pass `--json`, which moves it to stderr. So pass `--json` to `checkout`, `start` and `rm`, the commands here that can run them, and stdout holds only the result. [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) explains the rest of this contract.
- **Always name the verb.** `testlane my-project 42` with no verb runs the project's `default_command`, which is `code` unless the project or `defaults.toml` sets another, so it opens an editor.
- **Check the exit code before you read stdout.** When a command in this guide fails, it exits non-zero and prints nothing on stdout. [Handle a failure](#handle-a-failure) says what to do next.

## Drive a workspace

::steps{level="3"}

### List the projects

```bash
testlane projects --json
```

```json
[
  {
    "name": "my-project",
    "repo": "git@github.com:my-org/my-project.git",
    "workspaces": 0,
    "pathExists": false
  }
]
```

`name` is what every other command takes as `<project>`. `workspaces` counts the workspaces Testlane has checked out for it, and `pathExists` is `false` until the first checkout clones the repository. An empty array means no project is configured, so ask the user to add one rather than writing a config file yourself.

### Check out a ref and get its path

A ref is a PR number (`42`), a branch name (`feat/login`) or a full 40-character commit SHA. [Refs](https://testlane.dev/docs/concepts/refs) lists every form.

```bash
testlane my-project feat/login checkout --json
```

```json
{
  "project": "my-project",
  "slug": "feat-login",
  "ref": "feat/login",
  "kind": "branch",
  "branch": "feat/login",
  "path": "/home/you/dev/testlane/my-project/trees/feat-login",
  "ports": [4153],
  "created": true
}
```

`path` is the absolute path of the workspace, so run your own commands there. `created` is `false` when the workspace already existed, and the command is safe to repeat. For a PR, `kind` is `"pr"` and `branch` is `"pr/42"`.

Note that `checkout` skips the project's `[setup]`, like installing dependencies, unless you add `--setup`. `start` runs it for you.

### Start a command and get its URL

```bash
testlane my-project feat/login start dev --json
```

```json
{
  "project": "my-project",
  "slug": "feat-login",
  "command": "dev",
  "pid": 82622,
  "port": 4153,
  "url": "http://127.0.0.1:4153",
  "log": "/home/you/dev/testlane/my-project/trees/.data/feat-login/process.log",
  "startedAt": "2026-11-14T09:37:24.871Z",
  "reused": false
}
```

`start` checks out the ref if it isn't already, runs `[setup]`, starts the command in the background and returns once `url` accepts connections. The process keeps running after `start` exits. `dev` must be a name under `[commands]` in the project's config.

Keep in mind that `start` can take minutes, since `[setup]` usually installs dependencies first. After setup, it waits up to 300 seconds for the port, and `--timeout <seconds>` changes that wait. Give your own tool call enough time.

`start` is safe to repeat. When the same command is already running, it prints the same object with `"reused": true`.

### Check what's running

```bash
testlane my-project ps --json
```

```json
[
  {
    "slug": "feat-login",
    "command": "dev",
    "pid": 82622,
    "port": 4153,
    "status": "running",
    "startedAt": "2026-11-14T09:37:24.871Z",
    "log": "/home/you/dev/testlane/my-project/trees/.data/feat-login/process.log"
  }
]
```

`ps` takes the project only, with no ref, and lists every process `start` left in it. `status` is `running`, or `exited` when the process died on its own, like after a crash. With nothing started, it prints `[]`.

### Read the logs

`logs` has no `--json`. It prints the process's log on stdout, as it is:

```bash
testlane my-project feat/login logs
```

```
listening on 4153
```

The log keeps growing while the process runs, so we recommend reading only its end, like `testlane my-project feat/login logs | tail -n 50`. Never pass `-f` or `--follow`: they keep printing until someone interrupts them, so your call never returns. With no log yet, `logs` exits `2`.

### Stop the process

`stop` has no `--json`. Read its exit code, which is `0` whether or not anything was running:

```bash
testlane my-project feat/login stop
```

stderr says what happened, like `→ dev stopped (pid 82622)` or `→ not running: my-project/feat-login`. The log stays, so you can still read it after `stop`.

### Remove the workspace

`rm` asks for confirmation, so pass `--yes`. It prints no JSON, but pass `--json` anyway: it moves the output of the project's `pre_clean` hook to stderr, so stdout holds only the slugs `rm` removed.

```bash
testlane my-project feat/login rm --yes --json
```

```
feat-login
```

stdout names each slug it removed. `rm` stops a running process first, so you don't need `stop` before it. When stdin isn't a terminal, `rm` without `--yes` exits `2` instead of asking.

`rm` keeps the workspace when it has uncommitted changes, or when the project's `pre_clean` hook fails. Either way, it exits `0`, prints nothing on stdout and warns on stderr with one of these lines:

```
warning: skipping feat-login: worktree is dirty (use --force)
warning: pre_clean hook failed for feat-login — skipping
```

So check that stdout names the slug. When the hook failed, report it to the user. When the workspace has uncommitted changes, `--force` removes it anyway and throws those changes away, and for a branch workspace it also deletes the local branch, so ask the user before you add it.

::

## Handle a failure

Testlane exits `0` on success. Any other code means the command failed, and stderr ends with one `error(E_…)` line and sometimes a `hint:` line:

```
error(E_SETUP): 'dev' exited before 127.0.0.1:4164 accepted connections
hint: full log: /home/you/dev/testlane/my-project/trees/.data/pr-42/process.log
```

Report both lines to the user, and don't retry the same command unchanged, since it usually fails the same way. This is what each code usually asks of an agent:

| Code | Name         | What to do                                                                      |
| ---- | ------------ | ------------------------------------------------------------------------------- |
| `1`  | `E_INTERNAL` | Stop and report it, since it's a bug in Testlane                                |
| `2`  | `E_USAGE`    | Fix the command, like a missing `--yes` or a command name that isn't configured |
| `3`  | `E_CONFIG`   | Report it, and leave fixing the config to the user                              |
| `4`  | `E_RESOLVE`  | Check the ref, then ask the user which one they meant                           |
| `5`  | `E_GIT`      | Report it, since a `git` or `gh` command failed                                 |
| `6`  | `E_SETUP`    | Read the lines above the error and `logs`, then report what failed              |

[Exit codes](https://testlane.dev/docs/cli/exit-codes) is the full reference.

A few cases come up often. `start` exits `2` when another command already runs in that workspace, and its hint names the `stop` to run first. It exits `6` when the command exits before its port is ready, when the port isn't ready within `--timeout` or when something else already holds the port. In each case it leaves no process behind.

## Keep an agent away from these commands

These commands open something for a person and wait for them, so an agent's call never returns:

- **`shell`** starts an interactive shell in the workspace. Run your commands in the `path` from `checkout` instead, or use `exec`, like `testlane my-project 42 exec -- npm test`.
- **`code`** opens the workspace in an editor. With a terminal editor like `vim`, it waits until someone closes it. Open `path` with your own tools.
- **`config edit`** and **`config add`** open a project's config file in an editor. `add` is another name for `edit`. Leave config changes to the user.

Two more need care. `run` waits until its command exits, which is right for `run test` and wrong for a dev server, so use `start` for anything that keeps running. And bare `testlane <project>` opens a picker that waits for a choice when it runs in a terminal, so use `testlane <project> list --json` to list workspaces.

## Connect over MCP

If your agent speaks the Model Context Protocol (MCP), you can skip the shell
commands above. `testlane mcp` serves the same steps as typed tools, and each
tool returns the same JSON as its command's `--json`. Your MCP client starts the
server itself, so you only add it to the client's config once.

[Agents](https://testlane.dev/docs/getting-started/agents#mcp) shows how to add the server to Claude Code and to clients with a JSON config.

The server has twelve tools. `projects`, `doctor` and `config_validate` take no
parameters. The others take `project`, and the workspace tools also take `ref`,
plus an optional `kind` of `pr`, `branch` or `path` in place of
`--pr`, `--branch` and `--path`:

| Tool | Command | Returns |
|---|---|---|
| `projects` | `testlane projects --json` | its JSON |
| `doctor` | `testlane doctor --json` | its JSON |
| `config_validate` | `testlane config validate --json` | its JSON |
| `list` | `testlane <project> list --json` | its JSON |
| `ps` | `testlane <project> ps --json` | its JSON |
| `info` | `testlane <project> <ref> info --json` | its JSON |
| `checkout` | `testlane <project> <ref> checkout --json` | its JSON |
| `start` | `testlane <project> <ref> start <command> --json` | its JSON |
| `stop` | `testlane <project> <ref> stop` | `{exitCode, stdout, stderr}` |
| `logs` | `testlane <project> <ref> logs`, its last `lines` lines | `{exitCode, stdout, stderr}` |
| `diff` | `testlane <project> <ref> diff` | `{exitCode, stdout, stderr}` |
| `rm` | `testlane <project> <ref> rm --yes` | `{exitCode, stdout, stderr, removed}` |

A tool that fails returns `isError: true`. When the command threw an error, the
text is `{"error": {"errCode", "exitCode", "message", "hint"}, "stderr"}`, so read
it the way [Handle a failure](#handle-a-failure) reads stderr. A few behaviours
differ from the shell:

- **`checkout` and `start` take a `timeout`,** in seconds (600 by default) for the
  whole call. When it runs out, the server stops the setup, hooks or server the
  call started and answers `{"timedOut": true, ...}`. While they run, they send
  progress for each step and at least every 5 seconds, when your client asks for
  progress.
- **`logs` returns the last 100 lines,** or as many as `lines` asks for, up to
  1000. It never follows the log.
- **`diff` returns at most 1 MiB,** with `"truncated": true` when there was more.
- **`rm` reports a kept workspace as an error.** When the workspace has
  uncommitted changes, or its `pre_clean` hook failed, `rm` keeps it and returns
  `"removed": false` with `isError: true`. The tool has no `force`, so only the
  user can throw those changes away.

`shell`, `code`, `exec`, `run`, `sync`, `clean` and `config edit` aren't tools,
since they wait for a person, run any command or remove many workspaces at once.
The server never records trust in a repository's config for the user either.
[ADR-003](https://github.com/uxfront-com/testlane/blob/main/docs/adrs/003-mcp-server.md)
gives the reason for each tool that's left out.

## Where to go next

Here's where to go from here:

- [Agent instructions](https://testlane.dev/docs/getting-started/agents#agent-instructions) has these rules as a short block to paste into
  `AGENTS.md` or `CLAUDE.md`.
- [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) covers the JSON of
  `list` and `info`, and patterns for shell scripts and CI.
- [Workspace verbs](https://testlane.dev/docs/cli/workspace-verbs) lists every flag of
  `checkout`, `start`, `stop`, `logs` and `rm`.
- [Run dev servers in parallel](https://testlane.dev/docs/guides/run-dev-servers-in-parallel)
  explains the ports `start` serves on.
