CLI Reference

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.

Workspace verbs let you do something with one ref: open it, run a command in it, bring it up to date, start its server in the background or remove it. Each takes a project and a ref. The verbs that open or run something create the workspace first when it doesn't exist yet, so you never need a separate checkout step before run or start:

testlane <project> <ref> <verb> [flags] [-- passthrough]

At a glance

VerbWhat it doesRuns [setup]--json
checkoutCreates the workspace and prints its pathWith --setupYes
codeOpens the workspace in your editorWith --setupNo, exits 2
run <name>Runs a command from [commands] in the workspaceYesNo
exec -- <argv…>Runs any program in the workspace, without a shellYesNo
shellOpens an interactive shell in the workspaceYesNo
syncFetches the ref again and resets the workspace to itNoNo
diffShows what the ref changesNoNo
infoShows one workspace in detailNoYes
rmRemoves the workspaceNoNo
start <name>Runs a command in the background and waits for its portYesYes
stopStops what start left runningNoNo
logsPrints the log of what start ranNoNo

[setup] runs the first time, then again only when its cache_key files change, so a verb that runs it is quick the second time. run, exec, shell and start also run the pre_run hook after it. Commands and hooks covers both.

The ref can be a branch, a PR number, a full commit SHA, a path or - for the last ref you used, as Refs explains. Note that info and rm don't take - yet, so name the ref for those two. Every verb also takes the global flags.

checkout

checkout creates the workspace and prints its absolute path on stdout, and nothing else, so it's the verb to call from scripts.

testlane <project> <ref> checkout [--fetch] [--setup]
FlagWhat it doesDefault
--fetchFetch the ref again when the workspace already existsOff
--setupRun [setup] tooOff
--no-setupAccepted for symmetry with run, and changes nothing, since checkout skips [setup] alreadyOff
testlane my-project feat/login checkout
→ cloning git@github.com:my-org/my-project.git (bare, partial)
→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
/home/you/dev/testlane/my-project/trees/feat-login

The → lines go to stderr, so cd "$(testlane my-project feat/login checkout)" gets the path alone. The clone happens once per project, and a second checkout of the same ref reuses the workspace and prints → worktree ready (reused).

With --json, it prints one object with project, slug, ref, kind, branch, path, ports and created, which is false when the workspace already existed:

{"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":false}

code

code creates the workspace when it needs to, then opens it in your editor.

testlane <project> <ref> code [--editor <editor>] [--fetch] [--setup]
FlagWhat it doesDefault
--editor <editor>Open this editor instead, a preset like cursor or a template with {path}The project's editor
--fetchFetch the ref again when the workspace already existsOff
--setupRun [setup] before openingOff
--no-setupAccepted, and changes nothing, as on checkoutOff
testlane my-project 42 code
testlane my-project 42 code --editor cursor

A GUI editor like code or cursor opens in the background, and testlane exits straight away. A terminal editor like vim takes over the terminal, and testlane exits with the editor's exit code. code prints nothing on stdout, and --json is a usage error (exit 2). Editors lists the presets.

run <name>

run runs one of the project's commands in the workspace, with its ports, data directory and environment set.

testlane <project> <ref> run <name> [--port <n>] [--env K=V]… [--no-setup] [--reseed] [--fetch] [-- args]
FlagWhat it doesDefault
--port <n>Use this port as {port} and $TESTLANE_PORT for this run only. The workspace keeps its ownThe workspace's first port
--env K=VAdd or override one environment variable. Repeat it for moreNone
--no-setupSkip [setup] and pre_runOff
--reseedCopy the seed files again, over the ones in the workspaceOff
--fetchFetch the ref again when the workspace already existsOff
testlane my-project 42 run test -- --watch
→ worktree ready (reused)
→ setup up to date (cache hit)
running tests --watch

Testlane runs the command's run string with bash -c in the worktree, or in the command's cwd, and appends the arguments after -- safely quoted. testlane my-project 42 test does the same as run test, since a command name works as a verb.

run exits with the command's own exit code, and passes Ctrl-C on to it. An unknown command name exits 2 and lists the ones you have:

error(E_USAGE): unknown command 'nope'
hint: configured commands: dev, test

With --dry-run, it prints the environment as export lines, then the command, and runs nothing. That's the quickest way to see what a command will get:

testlane my-project 42 run dev --dry-run
export TESTLANE_PATH=/home/you/dev/testlane/my-project/trees/pr-42
export TESTLANE_REPO_PATH=/home/you/dev/testlane/my-project/repo
export TESTLANE_DATA_DIR=/home/you/dev/testlane/my-project/trees/.data/pr-42
export TESTLANE_PROJECT=my-project
export TESTLANE_REF=42
export TESTLANE_BRANCH=pr/42
export TESTLANE_SLUG=pr-42
export TESTLANE_PORT=4164
export PORT=4164
bash -c 'node server.js "$@"' testlane

Before the export lines, it prints the git commands that would create the workspace.

exec -- <argv…>

exec runs any program in the workspace, like pnpm why or git log, without a command in the project file.

testlane <project> <ref> exec [--no-setup] [--reseed] [--fetch] -- <argv…>
FlagWhat it doesDefault
--no-setupSkip [setup] and pre_runOff
--reseedCopy the seed files again, over the ones in the workspaceOff
--fetchFetch the ref again when the workspace already existsOff
testlane my-project 42 exec -- git log --oneline -2
→ worktree ready (reused)
→ setup up to date (cache hit)
f8c6c89 pr 42
3a526ea initial

Everything after -- is the program and its arguments. Testlane starts it directly, with no shell in between, so nothing gets quoted twice. It sees the same environment as run, and exec exits with its exit code. Leaving out -- or the program exits 2.

Note that exec doesn't take --port or --env. When you need either, add a command to the project file and use run.

shell

shell opens an interactive shell in the workspace, with the whole Testlane environment exported, like $TESTLANE_PORT, $TESTLANE_PATH and $TESTLANE_DATA_DIR.

testlane <project> <ref> shell [--no-setup] [--reseed] [--fetch]
FlagWhat it doesDefault
--no-setupSkip [setup] and pre_runOff
--reseedCopy the seed files again, over the ones in the workspaceOff
--fetchFetch the ref again when the workspace already existsOff
testlane my-project 42 shell
testlane my-project - shell

It starts your $SHELL, or bash when that's unset, and prints one line on stderr first, with the project, the slug, the port and the path:

testlane: my-project/pr-42 — port 4164 — /home/you/dev/testlane/my-project/trees/pr-42

exit takes you back, and shell exits with the shell's exit code.

sync

sync fetches the ref again and resets the workspace to it, so a PR you reviewed yesterday shows today's commits.

testlane <project> <ref> sync [--stash | --discard | --fresh]
FlagWhat it doesDefault
--stashStash your changes with git stash, then resetOff
--discardThrow your changes away, untracked files included, then resetOff
--freshRemove the workspace and create it again. Stops with exit code 5 when it has changesOff

With none of them, sync stops with exit code 5 when the workspace has changes, and the three can't be combined. A branch resets to its upstream on origin, and a PR to its latest head.

testlane my-project feat/login sync --stash
→ fetching origin/feat/login
→ 541800a1 → 541800a1, 0 file(s) changed, stashed stash@{0}

The summary on stderr gives the commit before and after, how many files changed and the stash it made, if any. sync prints nothing on stdout, and runs the post_sync hook after the reset.

--discard deletes your changes and untracked files for good, and --fresh removes the workspace and its data directory before it creates them again. Run testlane <project> <ref> exec -- git status first when you're not sure what's there.

A ref with no workspace yet exits 4 and suggests checkout. Refresh a workspace walks through when to use each flag.

diff

diff shows what the ref changes, compared with your default branch.

testlane <project> <ref> diff [--stat] [--tool] [-- git-diff-args]
FlagWhat it doesDefault
--statShow a summary of changed files instead of the patchOff
--toolOpen the changes in git difftoolOff
testlane my-project 42 diff --stat
 README.md | 1 +
 pr.md     | 1 +
 2 files changed, 2 insertions(+)

For a plain diff of a PR, when gh is installed and signed in, Testlane shows gh pr diff, which compares against the PR's real base. Otherwise, and whenever you pass --stat, --tool or arguments after --, it runs git diff in the worktree from the merge base with origin/<default_branch> to HEAD. Arguments after -- go to git diff:

testlane my-project 42 diff -- --name-only

Keep in mind that the merge base needs default_branch in the project file. Without it, diff shows only the changes you haven't committed. A ref with no workspace exits 4.

info

info shows one workspace in detail, as key: value lines.

testlane <project> <ref> info [--du]
FlagWhat it doesDefault
--duAdd the disk space the workspace usesOff
testlane my-project feat/login info --du
slug: feat-login
kind: branch
ref: feat/login
branch: feat/login
path: /home/you/dev/testlane/my-project/trees/feat-login
ports: 4153
status: clean
created: 2026-11-14T09:38:05.950Z
last used: 2026-11-14T09:38:06.780Z
disk: 20.0KB

A PR workspace adds pr and pr url lines once gh has fetched its title and state. With --json, info prints the workspace's entry from Testlane's state, like slug, ref, kind, branch, path, ports, createdAt and lastUsedAt, plus dirty and missing, and diskBytes with --du. A ref with no workspace prints a warning and exits 4.

rm

rm removes one workspace: its worktree, its data directory and its entry in Testlane's state.

testlane <project> <ref> rm [--force] [--yes]
FlagWhat it doesDefault
--forceRemove the workspace even when it has changes, and delete its local branchOff
--yesSkip the confirmation promptOff
testlane my-project 42 rm --yes
→ plan:
  pr-42 (clean, 20 KB)
pr-42
→ freed 20 KB

rm prints its plan first, then asks before it removes anything. Without a terminal to ask on, it needs --yes, or it exits 2. Once it's done, it prints the removed slug on stdout. A workspace with changes is skipped with a warning, and rm still exits 0:

warning: skipping feat-login: worktree is dirty (use --force)
--force throws away the workspace's changes. On a branch workspace, it also deletes the local branch in Testlane's clone, while the branch on origin stays.

Before it removes anything, rm runs the pre_clean hook, which can stop the removal, then stops any process start left running. An adopted workspace keeps its directory, and only its data directory goes. To remove several workspaces at once, use clean.

start <name>

start runs one of the project's commands in the background and returns once its port answers, so you can hand someone a running app and get your terminal back.

testlane <project> <ref> start <name> [--timeout <seconds>] [--env K=V]… [--no-setup] [--reseed] [--fetch] [-- args]
FlagWhat it doesDefault
--timeout <seconds>How long to wait for the port, and for another start of the same workspace300
--env K=VAdd or override one environment variable. Repeat it for moreNone
--no-setupSkip [setup] and pre_runOff
--reseedCopy the seed files again, over the ones in the workspaceOff
--fetchFetch the ref again when the workspace already existsOff
testlane my-project 42 start dev
→ worktree ready (reused)
→ setup up to date (cache hit)
→ started dev (pid 97128), waiting for 127.0.0.1:4164
→ dev ready on http://127.0.0.1:4164 (pid 97128, log /home/you/dev/testlane/my-project/trees/.data/pr-42/process.log)
http://127.0.0.1:4164

start builds the command the way run does, then starts it in its own session and process group, with its output added to process.log in the workspace's data directory. It returns once 127.0.0.1:{port} accepts a connection, prints the URL on stdout and leaves the process running after testlane exits.

With --json, it prints one object with project, slug, command, pid, port, url, log, startedAt and reused.

A workspace runs one such process at a time, so start is safe to repeat:

  • The same command is running. start prints it with "reused": true and runs nothing, not even [setup] or hooks.
  • Another command is running. start exits 2, names it and gives you the stop to run first.
  • Two starts overlap. The second waits for the first, for as long as its own --timeout, then prints the process the first one started. When the wait runs out, it exits 5.

start exits 6 in three cases:

  • The command exits before its port is ready. start prints the last 20 lines of its log.
  • The port isn't ready within --timeout. start stops the process first.
  • Something else already answers on the port. start doesn't start your command, since it couldn't tell when your server is ready. By then, it has already opened the workspace and run [setup] (unless you passed --no-setup) and pre_run.

The check connects to 127.0.0.1 only, so bind your server to 127.0.0.1:$TESTLANE_PORT rather than localhost or ::1. --port is a usage error here, since the process always serves the workspace's own port, so hooks and ps see the same one. --dry-run prints the environment and the command, as run does, and starts nothing.

When the project has a command named start, stop or logs, the verb wins. Reach the command with testlane my-project 42 run start.

stop

stop stops the process start left running and clears its record, while its log stays.

testlane <project> <ref> stop

For example, testlane my-project 42 stop prints:

→ dev stopped (pid 97128)

stop sends SIGTERM to the whole process group, then SIGKILL to anything left after 10 seconds, so a dev server that bash -c started stops too. It signals the PID only while that PID still has the start time it had when start recorded it, so a PID the system has since given to another process is left alone. With nothing running, it says so and exits 0:

→ not running: my-project/pr-42

rm and clean stop a running process the same way before they remove its workspace.

logs

logs prints the log of the process start ran, and can follow it as it grows.

testlane <project> <ref> logs [-f]
FlagWhat it doesDefault
-f, --followKeep printing new lines until you press Ctrl-COff
testlane my-project 42 logs
listening on 127.0.0.1:4164

The log survives stop, a restart adds to it and it goes when the workspace does. With no log yet, logs exits 2:

error(E_USAGE): no log for my-project/pr-42
hint: start a command first: testlane my-project <ref> start <name>
Copyright © 2026