CLI Reference

Command Grammar

The three shapes every Testlane command takes, what runs when you leave the verb out, and where each verb is documented.

Every testlane command is a project, a ref and a verb, or a shorter form of that, so once you know the shape you can guess most commands before you look them up. This page explains the shapes, what Testlane does when you leave a part out and where each verb is documented. Reach for it when a command does something you didn't expect.

At a glance

ShapeUsageVerbs
Workspace commandtestlane <project> <ref> [verb] [flags] [-- passthrough]Workspace verbs: checkout, code, run, exec, shell, sync, diff, info, rm, start, stop and logs
Project commandtestlane <project> [verb] [flags]Project verbs: list, clean and ps
Top-level commandtestlane <verb> [args]Top-level verbs: setup, projects, doctor, config, completions, mcp, help and version
No verb after a reftestlane <project> <ref>The project's default_command, which is code unless you set it
No reftestlane <project>A picker on a terminal, list everywhere else
Global flagsAnywhere before --Global flags
Errorserror(E_…): … on stderrExit codes

The three shapes

Let's start with how Testlane reads a command. It looks at the first word, then the second, then the third:

testlane <project> <ref> [verb] [flags] [-- passthrough]
testlane <project> [list|clean|ps] [flags]
testlane <top-level-verb> [args]
PositionWhat it is
First wordA top-level verb like doctor, or the name of a project, which is a file <name>.toml in the config directory. A repository URL also works here, as Refs explains
Second wordA project verb (list, clean or ps), or else a ref: a branch, a PR number, a full commit SHA, a path or -
Third wordA workspace verb, or the name of a command under [commands] in the project file
-- passthroughEverything after the first --, handed as it is to the command that runs

The third word can be a command name because Testlane reads testlane my-project 42 test as testlane my-project 42 run test. When a command shares its name with a verb, like a command called start, the verb wins, and run start reaches the command. testlane doctor warns you about such names.

Passthrough arguments reach the command, never Testlane:

testlane my-project 42 run test -- --watch

Here --watch goes to your test runner. A word Testlane doesn't recognise in the third position stops with exit code 2 and suggests run:

error(E_USAGE): unknown command 'bogus'
hint: did you mean 'run bogus'? configured commands: dev, test

Leaving the verb out

Now let's look at what runs when you leave the verb out. After a ref, Testlane runs the project's default_command, which is code unless the project file or defaults.toml sets another. So testlane my-project 42 opens PR 42 in your editor. You can set it to checkout, code, shell, diff, info or the name of one of your commands, as Commands and hooks explains.

We recommend naming the verb in scripts, since default_command can change under them. checkout is the one to call when you want the path:

cd "$(testlane my-project 42 checkout)"

Leaving the ref out

Next, let's look at a project on its own. testlane my-project in a terminal lists the project's workspaces with a number each and asks you to pick one, then prints the path of the one you pick. An empty answer cancels. Without a terminal, like inside $(…) or a pipe, or with --json, it prints what list prints instead:

testlane my-project
SLUG        KIND    BRANCH      STATUS  PORT  AGE  LAST USED
main        branch  main        clean   4192  0m   0m
feat-login  branch  feat/login  clean   4153  0m   0m
pr-42       pr      pr/42       clean   4164  0m   0m

Built-in help

Finally, testlane help prints the same grammar, every verb, the global flags and the order Testlane looks for its config directory in, so you have the reference offline:

testlane help
testlane — materialize any git ref of a configured project into a runnable workspace

USAGE
  testlane <project> <ref> [verb] [flags] [-- passthrough]
  testlane <project> [list|clean|ps] [flags]
  testlane <top-level-verb> [args]

Note that testlane with no arguments prints the same text. Help and the version are verbs with no flag form, so use testlane help and testlane version.

Copyright © 2026