# Command Grammar

> The three shapes every Testlane command takes, what runs when you leave the verb out, and where each verb is documented.

Every `testlane` command is a project, a ref and a verb, or a shorter form of that, so once you know the shape you can guess most commands before you look them up. This page explains the shapes, what Testlane does when you leave a part out and where each verb is documented. Reach for it when a command does something you didn't expect.

## At a glance

| Shape | Usage | Verbs |
| --- | --- | --- |
| Workspace command | `testlane <project> <ref> [verb] [flags] [-- passthrough]` | [Workspace verbs](https://testlane.dev/docs/cli/workspace-verbs): `checkout`, `code`, `run`, `exec`, `shell`, `sync`, `diff`, `info`, `rm`, `start`, `stop` and `logs` |
| Project command | `testlane <project> [verb] [flags]` | [Project verbs](https://testlane.dev/docs/cli/project-verbs): `list`, `clean` and `ps` |
| Top-level command | `testlane <verb> [args]` | [Top-level verbs](https://testlane.dev/docs/cli/top-level-verbs): `setup`, `projects`, `doctor`, `config`, `completions`, `mcp`, `help` and `version` |
| No verb after a ref | `testlane <project> <ref>` | The project's `default_command`, which is `code` unless you set it |
| No ref | `testlane <project>` | A picker on a terminal, `list` everywhere else |
| Global flags | Anywhere before `--` | [Global flags](https://testlane.dev/docs/cli/global-flags) |
| Errors | `error(E_…): …` on stderr | [Exit codes](https://testlane.dev/docs/cli/exit-codes) |

## The three shapes

Let's start with how Testlane reads a command. It looks at the first word, then the second, then the third:

```
testlane <project> <ref> [verb] [flags] [-- passthrough]
testlane <project> [list|clean|ps] [flags]
testlane <top-level-verb> [args]
```

| Position | What it is |
| --- | --- |
| First word | A top-level verb like `doctor`, or the name of a project, which is a file `<name>.toml` in the config directory. A repository URL also works here, as [Refs](https://testlane.dev/docs/concepts/refs) explains |
| Second word | A project verb (`list`, `clean` or `ps`), or else a ref: a branch, a PR number, a full commit SHA, a path or `-` |
| Third word | A workspace verb, or the name of a command under `[commands]` in the project file |
| `-- passthrough` | Everything after the first `--`, handed as it is to the command that runs |

The third word can be a command name because Testlane reads `testlane my-project 42 test` as `testlane my-project 42 run test`. When a command shares its name with a verb, like a command called `start`, the verb wins, and `run start` reaches the command. `testlane doctor` warns you about such names.

Passthrough arguments reach the command, never Testlane:

```bash
testlane my-project 42 run test -- --watch
```

Here `--watch` goes to your test runner. A word Testlane doesn't recognise in the third position stops with exit code `2` and suggests `run`:

```
error(E_USAGE): unknown command 'bogus'
hint: did you mean 'run bogus'? configured commands: dev, test
```

## Leaving the verb out

Now let's look at what runs when you leave the verb out. After a ref, Testlane runs the project's `default_command`, which is `code` unless the project file or `defaults.toml` sets another. So `testlane my-project 42` opens PR 42 in your editor. You can set it to `checkout`, `code`, `shell`, `diff`, `info` or the name of one of your commands, as [Commands and hooks](https://testlane.dev/docs/configuration/commands-and-hooks) explains.

We recommend naming the verb in scripts, since `default_command` can change under them. `checkout` is the one to call when you want the path:

```bash
cd "$(testlane my-project 42 checkout)"
```

## Leaving the ref out

Next, let's look at a project on its own. `testlane my-project` in a terminal lists the project's workspaces with a number each and asks you to pick one, then prints the path of the one you pick. An empty answer cancels. Without a terminal, like inside `$(…)` or a pipe, or with `--json`, it prints what `list` prints instead:

```bash
testlane my-project
```

```
SLUG        KIND    BRANCH      STATUS  PORT  AGE  LAST USED
main        branch  main        clean   4192  0m   0m
feat-login  branch  feat/login  clean   4153  0m   0m
pr-42       pr      pr/42       clean   4164  0m   0m
```

## Built-in help

Finally, `testlane help` prints the same grammar, every verb, the global flags and the order Testlane looks for its config directory in, so you have the reference offline:

```bash
testlane help
```

```
testlane — materialize any git ref of a configured project into a runnable workspace

USAGE
  testlane <project> <ref> [verb] [flags] [-- passthrough]
  testlane <project> [list|clean|ps] [flags]
  testlane <top-level-verb> [args]
```

Note that `testlane` with no arguments prints the same text. Help and the version are verbs with no flag form, so use `testlane help` and `testlane version`.
