Workspace Verbs
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
| Verb | What it does | Runs [setup] | --json |
|---|---|---|---|
checkout | Creates the workspace and prints its path | With --setup | Yes |
code | Opens the workspace in your editor | With --setup | No, exits 2 |
run <name> | Runs a command from [commands] in the workspace | Yes | No |
exec -- <argv…> | Runs any program in the workspace, without a shell | Yes | No |
shell | Opens an interactive shell in the workspace | Yes | No |
sync | Fetches the ref again and resets the workspace to it | No | No |
diff | Shows what the ref changes | No | No |
info | Shows one workspace in detail | No | Yes |
rm | Removes the workspace | No | No |
start <name> | Runs a command in the background and waits for its port | Yes | Yes |
stop | Stops what start left running | No | No |
logs | Prints the log of what start ran | No | No |
[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]
| Flag | What it does | Default |
|---|---|---|
--fetch | Fetch the ref again when the workspace already exists | Off |
--setup | Run [setup] too | Off |
--no-setup | Accepted for symmetry with run, and changes nothing, since checkout skips [setup] already | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--editor <editor> | Open this editor instead, a preset like cursor or a template with {path} | The project's editor |
--fetch | Fetch the ref again when the workspace already exists | Off |
--setup | Run [setup] before opening | Off |
--no-setup | Accepted, and changes nothing, as on checkout | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--port <n> | Use this port as {port} and $TESTLANE_PORT for this run only. The workspace keeps its own | The workspace's first port |
--env K=V | Add or override one environment variable. Repeat it for more | None |
--no-setup | Skip [setup] and pre_run | Off |
--reseed | Copy the seed files again, over the ones in the workspace | Off |
--fetch | Fetch the ref again when the workspace already exists | Off |
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…>
| Flag | What it does | Default |
|---|---|---|
--no-setup | Skip [setup] and pre_run | Off |
--reseed | Copy the seed files again, over the ones in the workspace | Off |
--fetch | Fetch the ref again when the workspace already exists | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--no-setup | Skip [setup] and pre_run | Off |
--reseed | Copy the seed files again, over the ones in the workspace | Off |
--fetch | Fetch the ref again when the workspace already exists | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--stash | Stash your changes with git stash, then reset | Off |
--discard | Throw your changes away, untracked files included, then reset | Off |
--fresh | Remove the workspace and create it again. Stops with exit code 5 when it has changes | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--stat | Show a summary of changed files instead of the patch | Off |
--tool | Open the changes in git difftool | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--du | Add the disk space the workspace uses | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--force | Remove the workspace even when it has changes, and delete its local branch | Off |
--yes | Skip the confirmation prompt | Off |
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]
| Flag | What it does | Default |
|---|---|---|
--timeout <seconds> | How long to wait for the port, and for another start of the same workspace | 300 |
--env K=V | Add or override one environment variable. Repeat it for more | None |
--no-setup | Skip [setup] and pre_run | Off |
--reseed | Copy the seed files again, over the ones in the workspace | Off |
--fetch | Fetch the ref again when the workspace already exists | Off |
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.
startprints it with"reused": trueand runs nothing, not even[setup]or hooks. - Another command is running.
startexits2, names it and gives you thestopto 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 exits5.
start exits 6 in three cases:
- The command exits before its port is ready.
startprints the last 20 lines of its log. - The port isn't ready within
--timeout.startstops the process first. - Something else already answers on the port.
startdoesn'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) andpre_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]
| Flag | What it does | Default |
|---|---|---|
-f, --follow | Keep printing new lines until you press Ctrl-C | Off |
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>