CLI Reference

Exit Codes

Every Testlane exit code, the error name that goes with it, what it means and the error output around it.

Exit codes let a script tell what went wrong without reading the message: a typo in a flag, a project that isn't set up, a branch that doesn't exist or a server that didn't start. Every error also prints a name, like E_RESOLVE, so you can find it here and in Troubleshooting.

At a glance

CodeNameWhat it meansFor example
0NoneSuccessThe command did what you asked
1E_INTERNALSomething failed that Testlane didn't expect, or a doctor check failedA bug, or FAIL in doctor
2E_USAGEThe command doesn't make senseAn unknown flag, a missing --yes, a command start can't run next to another
3E_CONFIGThe config is missing or wrongAn unknown project, a file that doesn't validate, no config directory, a repository's .testlane.toml you haven't approved
4E_RESOLVEThe ref or the workspace can't be foundA branch that isn't on origin, a ref with no workspace for sync or info
5E_GITA git or gh command failed, or git would lose worksync on a workspace with changes, a lock that times out
6E_SETUP[setup], a hook that can block or start failedAn install that fails, a server that never opens its port, a program exec can't find

Error output

Let's start with what an error looks like. It's one line on stderr with the name and the message, often followed by a hint that says what to do:

error(E_CONFIG): unknown project 'nope'
hint: known projects: my-project
error(E_RESOLVE): branch 'nope' does not exist on origin
hint: check the name, or push the ref first
error(E_USAGE): unsupported shell 'ksh'
hint: one of: bash, zsh, fish

The error goes to stderr only, so it never ends up in what a script captures from stdout. With -v or TESTLANE_DEBUG=1, the stack trace follows the hint.

Codes from your own commands

Now let's look at the codes Testlane passes on. run, exec, shell and code with a terminal editor like vim exit with the exit code of what they ran, so a failing test run fails the same way under Testlane:

testlane my-project feat/login exec -- sh -c 'exit 7'
echo $?
7

Keep in mind that such a code can match one in the table above, so a test runner that exits 2 looks like a usage error. When you need to tell them apart, check stderr for a line that starts with error(, which is how Testlane prints its own errors.

Branching on the code

Finally, let's look at scripts. We recommend branching on the exit code rather than the message, since the wording of a message can change between versions while the codes don't:

testlane my-project feat/login checkout -q
case $? in
  0) echo "ready" ;;
  4) echo "no such branch, push it first" ;;
  *) echo "something else went wrong" ;;
esac

Note that a failing outside tool other than git, like gh, can print the name E_EXTERNAL, with the same code 5 as E_GIT. Script with Testlane has more patterns, and Troubleshooting has a fix for each error.

Copyright © 2026