# 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

| Verb | What it does | Runs `[setup]` | `--json` |
| --- | --- | --- | --- |
| [`checkout`](#checkout) | Creates the workspace and prints its path | With `--setup` | Yes |
| [`code`](#code) | Opens the workspace in your editor | With `--setup` | No, exits `2` |
| [`run <name>`](#run-name) | Runs a command from `[commands]` in the workspace | Yes | No |
| [`exec -- <argv…>`](#exec-argv) | Runs any program in the workspace, without a shell | Yes | No |
| [`shell`](#shell) | Opens an interactive shell in the workspace | Yes | No |
| [`sync`](#sync) | Fetches the ref again and resets the workspace to it | No | No |
| [`diff`](#diff) | Shows what the ref changes | No | No |
| [`info`](#info) | Shows one workspace in detail | No | Yes |
| [`rm`](#rm) | Removes the workspace | No | No |
| [`start <name>`](#start-name) | Runs a command in the background and waits for its port | Yes | Yes |
| [`stop`](#stop) | Stops what `start` left running | No | No |
| [`logs`](#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](https://testlane.dev/docs/configuration/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](https://testlane.dev/docs/concepts/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](https://testlane.dev/docs/cli/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 |

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

```json
{"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 |

```bash
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](https://testlane.dev/docs/configuration/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 |

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

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

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

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

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

::warning
`--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](https://testlane.dev/docs/guides/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 |

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

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

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

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

::warning
`--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`](#start-name) left running. An adopted workspace keeps its directory, and only its data directory goes. To remove several workspaces at once, use [`clean`](https://testlane.dev/docs/cli/project-verbs#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 |

```bash
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`](https://testlane.dev/docs/cli/project-verbs#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`](https://testlane.dev/docs/cli/project-verbs#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 |

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