# Script with Testlane

> Drive Testlane from shell scripts and CI, with data on stdout, JSON you can parse and exit codes you can branch on.

By the end of this guide, your scripts and CI jobs open workspaces with Testlane and act on the result without parsing a line meant for people. Testlane is built to be driven by other programs, and three rules make that safe: data goes to stdout and everything else to stderr, `--json` gives you a shape to parse and every failure has an exit code of its own.

## Before you start

You'll need Testlane [installed](https://testlane.dev/docs/getting-started/installation) and a configured project, which we'll call `my-project`. The examples use [`jq`](https://jqlang.org) to read JSON.

## Script your first workspace

::steps{level="3"}

### Check out a ref as JSON

```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}
```

Each result is one line of JSON on stdout. `path` is the workspace's absolute path, and `created` is `false` when the workspace already existed, which tells you whether a first-time step still needs to run. The progress lines, and the output of any hook the checkout runs, go to stderr, so they reach your terminal without getting in the way.

### Check the exit code and move into the workspace

```bash
json=$(testlane my-project "$REF" checkout --json) || {
  code=$?
  [ "$code" -eq 4 ] && echo "unknown ref: $REF" >&2
  exit "$code"
}
cd "$(echo "$json" | jq -r .path)"
```

When a command fails, it prints nothing on stdout and exits with a code that says why, so read the code rather than the error text. Here, `4` means Testlane couldn't find the ref. We name the variable `code` rather than `status`, since `status` is read-only in zsh.

### Answer the prompts

```bash
testlane my-project clean --merged --yes
```

`clean` and `rm` ask before they remove anything. Without a terminal to ask in, they stop with `E_USAGE` (exit `2`), so add `--yes` in every script.

::

## Keep data and progress apart

Everything meant for people goes to stderr: progress lines (`→ …`), warnings (`warning: …`), errors and the commands `-v` prints (`· …`). Only the result goes to stdout, so `$(testlane …)` captures the data and nothing else.

There's one exception. The output of your project's `[setup]` and hooks goes to stdout too, unless you pass `--json`, which moves it to stderr. A plain `checkout` prints the path on stdout, but a `post_checkout` hook that prints something lands before it, so `$(testlane my-project 42 checkout)` can hold more than the path. So pass `--json`, or `--no-setup` where you don't need the install, whenever you capture the output of a command that can run them, like `checkout`, `run`, `exec` or `start`.

## Read the JSON

`checkout`, `list`, `info`, `start`, `ps`, `projects`, `doctor` and `config validate` take `--json`. Here are the four you'll use most.

`list --json` prints an array with one object per workspace:

```bash
testlane my-project list --json
```

```json
[{"slug":"feat-login","ref":"feat/login","kind":"branch","branch":"feat/login","path":"/home/you/dev/testlane/my-project/trees/feat-login","adopted":false,"ports":[4153],"createdAt":"2026-11-14T09:36:51.351Z","lastUsedAt":"2026-11-14T09:36:51.459Z","dirty":false,"missing":false}]
```

`info --json` prints one object of the same shape, for one workspace:

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

`projects --json` prints one object per project file:

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

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

`pathExists` is `false` until the first checkout clones the repository. The JSON of `start` and `ps` is in [Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent).

## Branch on the exit code

Every command exits `0` when it succeeds. Any other code tells you what went wrong:

| Code | Name         | What it means                       |
| ---- | ------------ | ----------------------------------- |
| `0`  |              | It worked                           |
| `1`  | `E_INTERNAL` | Something failed inside Testlane    |
| `2`  | `E_USAGE`    | A flag or argument is wrong         |
| `3`  | `E_CONFIG`   | A config is missing or invalid      |
| `4`  | `E_RESOLVE`  | Testlane couldn't find the ref      |
| `5`  | `E_GIT`      | A `git` or `gh` command failed      |
| `6`  | `E_SETUP`    | A setup step, a hook that can block or `start` failed |

A failure prints one `error(E_…)` line on stderr, often followed by a `hint:`:

```
error(E_RESOLVE): branch 'does-not-exist' does not exist on origin
hint: check the name, or push the ref first
```

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

## Examples

These are the patterns we reach for most.

Run a command in every workspace of a project:

```bash
testlane my-project list --json \
  | jq -r '.[].slug' \
  | while read -r slug; do
      testlane my-project "$slug" exec --no-setup -- git log -1 --oneline
    done
```

Run a first-time step only when the workspace is new:

```bash
created=$(testlane my-project "$REF" checkout --json | jq -r '.created')
[ "$created" = "true" ] && ./scripts/seed.sh
```

Remove every merged workspace in a nightly job:

```bash
testlane my-project clean --merged --yes
```

## Where to go next

Here's where to go from here:

- [Global flags](https://testlane.dev/docs/cli/global-flags) lists `--json`, `--yes`, `--quiet` and the rest.
- [Exit codes](https://testlane.dev/docs/cli/exit-codes) explains each code and when it happens.
- [Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent) applies the same rules to an AI coding agent.
