CLI Reference

Project Verbs

The verbs that take a project but no ref, list, clean and ps, with their columns, filters, flags and JSON.

Project verbs let you look after all of a project's workspaces at once: see what you have, remove what you're done with and check what's still running. Each takes a project and no ref:

testlane <project> <verb> [flags]

At a glance

VerbWhat it does--json
listLists the project's workspacesYes
cleanRemoves workspaces by slug or by filterNo
psLists the processes start left runningYes

list

list shows every workspace of the project, the one you used last at the top.

testlane <project> list [--du]
FlagWhat it doesDefault
--duAdd diskBytes, the disk space each workspace uses, to the --json outputOff
testlane my-project list
SLUG        KIND    BRANCH      STATUS  PORT  AGE  LAST USED
pr-42       pr      pr/42       clean   4164  0m   0m
feat-login  branch  feat/login  clean   4153  0m   0m
ColumnWhat it shows
SLUGThe workspace's name, which clean takes
KINDbranch, pr, commit or path, for a working tree you adopted
BRANCHThe branch checked out, or (adopted)
STATUSclean, dirty or missing. A PR also shows its state, like open, with ✓ or ✗ for its checks
PORTThe workspace's first port
AGEHow long ago the workspace was created
LAST USEDHow long ago a testlane command last used it

The PR state comes from gh. list asks it for anything older than a minute and waits two seconds at most, so the table shows up even when gh is slow or missing. With no workspaces, list says so:

→ no workspaces for 'my-project'

With --json, list prints an array of the workspaces' entries in Testlane's state, like slug, ref, kind, branch, path, adopted, ports, createdAt and lastUsedAt, plus dirty and missing. It never calls gh, so the output is the same online and offline:

[{"slug":"pr-42","ref":"42","kind":"pr","number":42,"branch":"pr/42","path":"/home/you/dev/testlane/my-project/trees/pr-42","adopted":false,"ports":[4164],"createdAt":"2026-11-14T09:38:11.563Z","lastUsedAt":"2026-11-14T09:38:11.723Z","dirty":false,"missing":false}]

testlane my-project with no verb prints this list too, except on a terminal, where it lets you pick a workspace, as Command grammar explains.

clean

clean removes several workspaces at once, either the slugs you name or every workspace a filter matches.

testlane <project> clean [<slug>…] [--all] [--merged] [--closed] [--older-than <age>] [--prune-state] [--include-adopted] [--force] [--yes]
FilterWhat it selects
--allEvery workspace
--mergedBranches merged into origin/<default_branch>, or origin/main when the project doesn't set one, checked with git alone
--closedPRs that are closed or merged, according to gh, or to the state gh last reported, or to --merged as a last resort
--older-than <age>Workspaces no command has used for at least <age>, like 90m, 36h, 7d or 2w
--prune-stateEntries in Testlane's state whose worktree is gone from disk
FlagWhat it doesDefault
--include-adoptedLet filters select adopted workspaces tooOff
--forceRemove workspaces that have changes, and delete their local branchesOff
--yesSkip the confirmation promptOff

Filters combine, so a workspace has to match all of them: --merged --older-than 7d removes only merged branches that nobody used for a week. Slugs and filters can't be combined, and clean with neither exits 2. A slug always selects its workspace, adopted or not.

testlane my-project clean main --yes
→ plan:
  main (clean, 16 KB)
main
→ freed 16 KB

clean always prints its plan first, with each workspace's reason, its state and its size, then asks before it removes anything. Without a terminal to ask on, it needs --yes:

error(E_USAGE): refusing to remove 1 workspace(s) without confirmation
hint: pass --yes for non-interactive use

Once it's done, it prints each removed slug on stdout and the space it freed on stderr. With --dry-run, it prints the plan and the commands it would run, and removes nothing. When nothing matches, it says → nothing to remove and exits 0.

A workspace with changes is skipped with a warning, unless you pass --force:

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

For each workspace, clean runs the pre_clean hook, which can keep it, then stops any process start left running, and removes it the way rm does. Clean up workspaces walks through a routine you can keep.

ps

ps lists the processes start left running in the project's workspaces, so you can see what's still serving before you clean up.

testlane <project> ps

For example, testlane my-project ps prints:

SLUG   COMMAND  PID    PORT  STATUS   STARTED                   LOG
pr-42  dev      97128  4164  running  2026-11-14T09:38:37.049Z  /home/you/dev/testlane/my-project/trees/.data/pr-42/process.log

STATUS is running while the recorded PID is alive and still has the start time it had, and exited otherwise, like after a crash or a restart of your machine. stop clears an exited entry. With no processes, ps says so:

→ no processes for 'my-project'

With --json, it prints an array of objects with slug, command, pid, port, status, startedAt and log, which is [] when nothing's running.

Copyright © 2026