Project Verbs
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
| Verb | What it does | --json |
|---|---|---|
list | Lists the project's workspaces | Yes |
clean | Removes workspaces by slug or by filter | No |
ps | Lists the processes start left running | Yes |
list
list shows every workspace of the project, the one you used last at the top.
testlane <project> list [--du]
| Flag | What it does | Default |
|---|---|---|
--du | Add diskBytes, the disk space each workspace uses, to the --json output | Off |
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
| Column | What it shows |
|---|---|
SLUG | The workspace's name, which clean takes |
KIND | branch, pr, commit or path, for a working tree you adopted |
BRANCH | The branch checked out, or (adopted) |
STATUS | clean, dirty or missing. A PR also shows its state, like open, with ✓ or ✗ for its checks |
PORT | The workspace's first port |
AGE | How long ago the workspace was created |
LAST USED | How 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]
| Filter | What it selects |
|---|---|
--all | Every workspace |
--merged | Branches merged into origin/<default_branch>, or origin/main when the project doesn't set one, checked with git alone |
--closed | PRs 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-state | Entries in Testlane's state whose worktree is gone from disk |
| Flag | What it does | Default |
|---|---|---|
--include-adopted | Let filters select adopted workspaces too | Off |
--force | Remove workspaces that have changes, and delete their local branches | Off |
--yes | Skip the confirmation prompt | Off |
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.