# 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

| Verb | What it does | `--json` |
| --- | --- | --- |
| [`list`](#list) | Lists the project's workspaces | Yes |
| [`clean`](#clean) | Removes workspaces by slug or by filter | No |
| [`ps`](#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 |

```bash
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:

```json
[{"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](https://testlane.dev/docs/cli/overview) 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.

```bash
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)
```

::warning
`--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`](https://testlane.dev/docs/cli/workspace-verbs#rm) does. [Clean up workspaces](https://testlane.dev/docs/guides/clean-up-workspaces) walks through a routine you can keep.

## `ps`

`ps` lists the processes [`start`](https://testlane.dev/docs/cli/workspace-verbs#start-name) 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`](https://testlane.dev/docs/cli/workspace-verbs#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.
