Command Grammar
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
| Shape | Usage | Verbs |
|---|---|---|
| Workspace command | testlane <project> <ref> [verb] [flags] [-- passthrough] | Workspace verbs: checkout, code, run, exec, shell, sync, diff, info, rm, start, stop and logs |
| Project command | testlane <project> [verb] [flags] | Project verbs: list, clean and ps |
| Top-level command | testlane <verb> [args] | Top-level verbs: setup, projects, doctor, config, completions, mcp, help and version |
| No verb after a ref | testlane <project> <ref> | The project's default_command, which is code unless you set it |
| No ref | testlane <project> | A picker on a terminal, list everywhere else |
| Global flags | Anywhere before -- | Global flags |
| Errors | error(E_…): … on stderr | Exit 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]
| Position | What it is |
|---|---|
| First word | A 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 word | A project verb (list, clean or ps), or else a ref: a branch, a PR number, a full commit SHA, a path or - |
| Third word | A workspace verb, or the name of a command under [commands] in the project file |
-- passthrough | Everything 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.
Ship a Config with Your Repo
Commit a .testlane.toml so everyone who adds your project gets working setup, env and commands, and see how users approve, override and keep up with it.
Workspace Verbs
Every verb that takes a project and a ref, from checkout and run to sync, start and rm, with its flags, output and exit codes.