CLI Reference

Global Flags

The flags every Testlane command takes, for the config directory, the kind of ref, dry runs, JSON output, how much it logs and prompts.

Global flags change how any command behaves rather than what it does: which config it reads, how it reads the ref, whether it changes anything and what it prints. You can put them anywhere before --, so testlane --json my-project list and testlane my-project list --json do the same.

At a glance

FlagWhat it doesApplies to
--config-dir <dir>Read the config from this directoryEvery command
--pr <n>, --branch <name>, --path <p>Read the ref as this kind, in place of the refWorkspace commands
--dry-runPrint what would run, and change nothingEvery command that changes something
--jsonPrint one JSON document on stdoutcheckout, list, info, start, ps, projects, doctor, config validate, config show and config detect
-q, --quietLeave out the → step linesEvery command
-v, --verboseAlso print every external command, and the stack trace of an errorEvery command
-y, --yesAnswer yes to every prompt, and approve a repository's configclean, rm, setup, config add, config trust and every command that checks a repository's config
--no-colorPrint no coloursEvery command

--config-dir

--config-dir <dir> points Testlane at another config directory for one command, like a test setup or a CI checkout. Testlane looks for the directory in this order, and takes the first one it finds:

  1. --config-dir <dir>.
  2. $TESTLANE_CONFIG_DIR.
  3. ~/.testlane, which setup creates.
testlane --config-dir ./ci-config projects

testlane config path prints the directory that won.

--pr, --branch and --path

These three tell Testlane what kind of ref you mean, for the names it could read two ways, like a branch called 42. Each one takes the ref as its value and replaces the ref in the command:

testlane my-project --branch 42 checkout    # a branch named "42"
testlane my-project --pr 42 info            # PR 42
testlane my-project --path ./hotfix shell   # a working tree you already have

You can give one of them at a time, and only to a workspace command. Anything else exits 2. Refs explains how Testlane reads a ref without them.

--dry-run

--dry-run shows what a command would do and changes nothing: it prints the commands it would run on stdout, one per line, takes no locks and asks no questions.

testlane my-project feat/login sync --discard --dry-run
git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options feat/login
git -C /home/you/dev/testlane/my-project/trees/feat-login reset --hard HEAD
git -C /home/you/dev/testlane/my-project/trees/feat-login clean -fd
git -C /home/you/dev/testlane/my-project/trees/feat-login reset --hard @{u}

run, exec, shell and start also print the environment the command would get, as export lines, then the command itself. setup prints the files it would write, and clean and rm print their plan.

--json

--json replaces the normal output with one JSON document on stdout, for scripts. Progress, warnings and what [setup] and hooks print all stay on stderr, so $(testlane … --json) captures clean JSON.

testlane my-project feat/login info --json

checkout, list, info, start, ps, projects, doctor and config validate support it, and each verb's section lists its fields. code exits 2 with it. The other verbs print no JSON, but --json still sends what [setup] and hooks print to stderr, so stdout holds only the verb's own output. That's why Use Testlane from an agent passes it to rm. Script with Testlane shows what you can build on it.

--quiet and --verbose

These two set how much Testlane says on stderr. -q leaves out the → step lines, so only the result is left. Warnings and errors still print:

testlane my-project feat/login checkout -q
/home/you/dev/testlane/my-project/trees/feat-login

-v adds a line starting with · for every external command Testlane runs, so you can see what it does for you:

→ fetching origin/main
· git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options main
· git -C /home/you/dev/testlane/my-project/repo worktree add /home/you/dev/testlane/my-project/trees/main -B main --track origin/main
→ worktree ready: /home/you/dev/testlane/my-project/trees/main
/home/you/dev/testlane/my-project/trees/main

With -v, an error also prints its stack trace, which is what to attach to a bug report. Setting TESTLANE_DEBUG=1 does the same without the extra lines.

--yes

-y answers yes to every prompt, for scripts and CI. clean and rm need it when there's no terminal to ask on, and exit 2 without it. setup takes the default root, ~/dev/testlane, instead of asking for it.

It also approves a repository's .testlane.toml when the trust check would ask. Testlane still prints the file, or the diff since you last trusted it, then records the approval without a question, so read what it prints in a script's log. Ship a config with your repo explains the trust check.

--no-color

--no-color turns colours off. Testlane also leaves them out when $NO_COLOR is set, or when stderr isn't a terminal, like when you pipe it to a file.

Copyright © 2026