Script with Testlane
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 and a configured project, which we'll call my-project. The examples use jq to read JSON.
Script your first workspace
Check out a ref as JSON
testlane my-project feat/login checkout --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
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
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:
testlane my-project list --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:
testlane my-project feat/login info --json
projects --json prints one object per project file:
testlane projects --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.
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 has the full reference.
Examples
These are the patterns we reach for most.
Run a command in every workspace of a project:
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:
created=$(testlane my-project "$REF" checkout --json | jq -r '.created')
[ "$created" = "true" ] && ./scripts/seed.sh
Remove every merged workspace in a nightly job:
testlane my-project clean --merged --yes
Where to go next
Here's where to go from here:
- Global flags lists
--json,--yes,--quietand the rest. - Exit codes explains each code and when it happens.
- Use Testlane from an agent applies the same rules to an AI coding agent.