# Top-Level Verbs

> The verbs that take no project, setup, projects, doctor, config, completions, mcp, help and version, with their flags and output.

Top-level verbs look after Testlane itself rather than one project: setting it up, checking your machine, editing the config and connecting your shell or an agent. Each one is the first word of the command, with no project before it:

```
testlane <verb> [args]
```

## At a glance

| Verb | What it does | `--json` |
| --- | --- | --- |
| [`setup`](#setup) | Creates the config directory and your first project file | No |
| [`projects`](#projects) | Lists the projects you've configured | Yes |
| [`doctor`](#doctor) | Checks your machine and every project file | Yes |
| [`config`](#config) | Prints, opens, checks, shows or trusts the config files, adds a project from its repository and drafts a config from a repository's files | `config validate`, `config show` and `config detect` |
| [`completions`](#completions) | Prints a completion script for your shell | No |
| [`mcp`](#mcp) | Serves Testlane's tools to an AI agent over MCP | No |
| [`help` and `version`](#help-and-version) | Prints the usage text or the version | No |

`setup`, `doctor`, `completions`, `mcp`, `help`, `version`, `config path`, `config add <url>` and `config detect <path>` work before the config directory exists. The others stop with exit code `3` until it does.

## `setup`

`setup` gets you from a fresh install to a working project: it creates the config directory, sets the base directory for clones and workspaces in `defaults.toml` and writes your first project file.

```
testlane setup [--name <name>] [--repo <url>] [--root <dir>] [--default-branch <branch>] [--force] [--detect]
```

| Flag | What it does | Default |
| --- | --- | --- |
| `--name <name>` | The project's name, and the name of its file, `<name>.toml` | Asked for |
| `--repo <url>` | The repository to clone, written as `repo` | Asked for |
| `--root <dir>` | The base directory for clones and workspaces, written to `defaults.toml` as `root` | `~/dev/testlane` |
| `--default-branch <branch>` | Written as `default_branch`, the branch `diff` and `clean --merged` compare against | None |
| `--force` | Overwrite the project file when it exists already | Off |
| `--detect` | Clone the repository and, when it has no `.testlane.toml`, write a config drafted from its files, as [`config detect`](#config-detect) does | Off |

On a terminal, `setup` asks for each value it doesn't have a flag for, so the same command also runs in CI with flags alone. It asks for the root only while `defaults.toml` has none. A name has to match `^[a-z0-9][a-z0-9._-]*$`, and can't be `defaults` or `seeds`. We recommend passing `--default-branch`, since `diff` needs it to find where a branch started.

Add `--dry-run` to see what it would write, and `--yes` to take the defaults without asking:

```bash
testlane setup --name my-project --repo git@github.com:my-org/my-project.git --default-branch main --yes --dry-run
```

```
mkdir -p /home/you/.testlane
write /home/you/.testlane/defaults.toml
  root = "~/dev/testlane"
write /home/you/.testlane/my-project.toml
  repo = "git@github.com:my-org/my-project.git"
  default_branch = "main"
```

Without `--dry-run`, it makes the same changes and tells you what to run next:

```
→ created config dir /home/you/.testlane
→ set defaults.root = ~/dev/testlane
→ scaffolded my-project.toml
→ next: testlane my-project main
```

`setup` checks the file it wrote with the same rules every command uses, so a mistake shows up now rather than on your next command. Before it writes anything, it stops with these exit codes:

| Exit code | When |
| --- | --- |
| `2` | The name isn't valid, the repository is empty or a value is missing with no terminal to ask on |
| `3` | The project file exists already and you didn't pass `--force`, which overwrites that file alone |

When the check itself fails, `setup` exits `3` with the file already on disk, so open it with `testlane config edit <project>` and fix what the error names.

With `--detect`, `setup` also clones the repository and checks its default branch for a `.testlane.toml`. When there is one, it asks you to trust it, as [`config add <url>`](#config-add-url) does, and the project file stays as written. When there's none, it writes the draft from [`config detect`](#config-detect) under the `repo` and `default_branch` lines, opens no editor, since `setup` runs unattended, and tells you to review it:

```
→ scaffolded my-project.toml
→ cloning git@github.com:my-org/my-project.git (bare, partial)
→ no .testlane.toml on origin/main
→ detecting a config from origin/main
→ wrote a detected config to /home/you/.testlane/my-project.toml; check each # guess: and # note: line
→ next: testlane config edit my-project
```

A failed clone puts back what `setup` wrote and exits `5`. With `--force` and a clone already there, it fetches the default branch instead of cloning again. When that clone is of another repository, `setup` puts the old file back and exits `3`, with a hint to remove the clone, so it never drafts from or trusts the wrong repository. With `--dry-run`, it also prints the clone commands and a `detect origin/<branch>` line.

## `projects`

`projects` lists the projects in the config directory, with their repository and how many workspaces each has.

```bash
testlane projects
```

```
NAME        REPO                                  WORKSPACES  PATH-EXISTS
my-project  git@github.com:my-org/my-project.git  2           yes
```

`PATH-EXISTS` says whether Testlane has cloned the project yet. A project file that doesn't load still shows up, with `?` as its repository, and `doctor` tells you why. With `--json`, `projects` prints an array of objects with `name`, `repo`, `workspaces` and `pathExists`:

```json
[{"name":"my-project","repo":"git@github.com:my-org/my-project.git","workspaces":2,"pathExists":true}]
```

## `doctor`

`doctor` checks your machine and every project file, and tells you what to fix, so it's the first thing to run when something doesn't work.

```bash
testlane doctor
```

```
OK   git version: git 2.50.1
WARN gh (github cli): missing or unauthenticated — PR metadata & push-back wiring degrade gracefully
OK   config dir: /home/you/.testlane
OK   state dir: /home/you/.local/state/testlane
OK   project my-project: config: schema-valid
OK   project my-project: repo file: trusted (sha256 b07a0b275b7f, approved 2026-11-14T08:14:17.327Z)
OK   project my-project: repo: bare repo at /home/you/dev/testlane/my-project/repo
OK   project my-project: fetch refspec: remote.origin.fetch configured
OK   project my-project: editor: vim (/usr/bin/vim)
```

Each line is `OK`, `WARN` or `FAIL`, then the check and what it found. `doctor` checks:

- **Your machine:** the git version, whether `gh` is installed and signed in, that the config directory is readable, that the state directory is writable, and stale lock files.
- **Each project:** that its file is valid, that its clone is a bare repository with a fetch refspec, that its editor preset is installed, commands named like a built-in verb, a `core.hooksPath` that can misbehave in worktrees, workspaces that git and Testlane's state disagree about, that its state file reads, and the repository's `.testlane.toml`, if it ships one.

The `repo file` check compares git blob ids, so it needs no network. It's `OK` when the repository has no `.testlane.toml`, when you've trusted the one it has, or when the project isn't cloned yet. It's `WARN` when the file is untrusted or has changed since you approved it, or when it's gone upstream while an approval is still stored. It's `FAIL` when the stored approval no longer validates:

```
WARN project my-project: repo file: .testlane.toml on origin/main changed since approval — run `testlane config trust my-project`
```

`doctor` exits `1` when any check fails, and `0` when there are only warnings. With `--json`, it prints `{"ok": …, "checks": […]}`, where each check has `name`, `status` (`ok`, `warn` or `fail`) and `detail`. [Troubleshooting](https://testlane.dev/docs/guides/troubleshooting) says what to do about each `WARN` and `FAIL`.

## `config`

`config` finds, opens and checks your config files, shows the config a run would use, and adds a project straight from its repository.

```
testlane config path
testlane config edit [project]
testlane config add [project]
testlane config add <url> [--name <name>] [--root <dir>]
testlane config validate [project]
testlane config show <project>
testlane config trust <project>
testlane config detect [path | project] [--repo-file]
```

| Subcommand | What it does |
| --- | --- |
| `path` | Prints the config directory in use. `testlane config` on its own does the same |
| `edit [project]` | Opens the project's file, or the config directory, in your editor. A project with no file yet gets a starter file first |
| `add [project]` | The same as `edit`, under the name you'd look for when adding a project |
| [`add <url>`](#config-add-url) | Adds a project from its repository, and asks you to trust the repository's `.testlane.toml` |
| `validate [project]` | Checks every project file, or one, against the schema |
| [`show <project>`](#config-show-project) | Prints the config a run would use, and where each key came from |
| [`trust <project>`](#config-trust-project) | Shows the repository's `.testlane.toml`, and records your approval |
| [`detect [path \| project]`](#config-detect) | Prints a config drafted from a repository's files |

```bash
testlane config path
```

```
/home/you/.testlane
```

`config path` is the quickest way to see which directory wins when `--config-dir` or `$TESTLANE_CONFIG_DIR` is set, as [Global flags](https://testlane.dev/docs/cli/global-flags) explains.

`edit` opens an existing project's file in that project's `editor`, and anything else in `$VISUAL` or `$EDITOR`. Keep in mind that Testlane reads those two the way it reads `editor`, so each needs to be a preset like `vim` or a template with `{path}`, like `nano {path}`. [Editors](https://testlane.dev/docs/configuration/editors) lists the presets. With `--dry-run`, `edit` prints the editor command, and the starter file when it would write one, and changes nothing.

`validate` exits `3` when a file has a problem, and prints each one on stderr as the file, the key and what's wrong:

```bash
testlane config validate
```

```
→ all project configs valid
```

With `--json`, a check of every file prints `{"ok": …, "issues": […]}`. Naming a project that has no file exits `2`. `validate` also checks the `.testlane.toml` you've approved for each project, as Testlane stored it.

### `config add <url>`

`config add <url>` adds a project from its repository, so you don't write any TOML when the repository ships a `.testlane.toml`.

```
testlane config add <url> [--name <name>] [--root <dir>] [--detect]
```

| Flag | What it does | Default |
| --- | --- | --- |
| `--name <name>` | The project's name, and the name of its file | The repository's name |
| `--root <dir>` | The base directory for clones and workspaces, written to `defaults.toml` as `root`, for a new machine | The `root` in `defaults.toml` |
| `--detect` | When the repository has no `.testlane.toml`, start the file from a config drafted from its files instead of the starter file | Off |

The URL is an ssh URL like `git@github.com:my-org/my-project.git`, or an https URL, a `/pull/<n>` or `/tree/<branch>` link included. An `ssh://` URL doesn't work here. `config add` then takes these steps:

1. It names the project after the repository, like `my-project`, unless you pass `--name`.
2. It writes `<name>.toml` with one line, `repo = "<clone url>"`: an ssh URL as you gave it, or `https://<host>/<owner>/<repo>.git`.
3. It clones the repository.
4. It shows the repository's `.testlane.toml` and asks you to trust it, as [`config trust`](#config-trust-project) does.

```bash
testlane config add https://github.com/my-org/my-project
```

```
→ wrote /home/you/.testlane/my-project.toml
→ cloning https://github.com/my-org/my-project.git (bare, partial)
my-project:.testlane.toml on origin/main would run:
  setup.run            pnpm install --frozen-lockfile
  commands.dev.run     pnpm dev --port {port}
  commands.test.run    pnpm test
  hooks.post_checkout  echo ready: {path}
--- my-project:.testlane.toml (origin/main) ---
…
---
Trust my-project:.testlane.toml? [y/N] y
→ trusted my-project:.testlane.toml (sha256 b07a0b275b7f)
→ next: testlane my-project main
```

When the repository has no `.testlane.toml`, `config add` writes the starter file with the real `repo` line and opens your editor, as `config add <project>` does. With `--detect`, it writes the draft from [`config detect`](#config-detect) instead, read from the default branch of the new clone, and opens that. A repository that has a `.testlane.toml` is trusted as above, and nothing is detected.

It needs a `root`, since the clone goes to `{root}/<name>/repo`. On a new machine, pass `--root <dir>`: it creates the config directory and writes `root` to `defaults.toml`, as `setup` does. Every check runs before anything is written, and `config add` stops with these exit codes:

| Exit code | When |
| --- | --- |
| `2` | The project name isn't valid, so pass `--name`, or `--root` differs from the `root` you already have |
| `3` | `<name>.toml` or a clone at the repository path exists already, or there's no `root` and no `--root`, with the hint `pass --root <dir>, for example --root ~/dev/testlane` |
| `3` | There's no terminal to ask on and no `--yes`. The project stays added, and the hint is `testlane config trust <name>` |
| `5` | The clone failed. `config add` puts back what it wrote |

With `--dry-run`, it prints the files it would write and the clone commands, and changes nothing. With `--detect` too, it adds a `detect origin/<default>` line.

### `config show <project>`

`config show` prints the config a run would use: your project file, merged with the `.testlane.toml` you approved, then `defaults.toml` and the built-in defaults. Each key ends with where it came from, `user`, `repo` or `default`:

```bash
testlane config show my-project
```

```
default_command = "dev"                             # repo
ports = 2                                           # repo
setup.run = "pnpm install --frozen-lockfile"        # repo
commands.dev.run = "pnpm dev --port {port} --open"  # user
commands.test.run = "pnpm test"                     # repo
→ my-project:.testlane.toml trusted at 2026-11-14T08:14:17.327Z (sha256 b07a0b275b7f)
```

That's an excerpt: the real output lists every key, `repo` and `repo_path` included. `config show` reads no git, so it needs no network. With `--json`, it prints one object:

```json
{"project":"my-project","approved":{"sha256":"b07a0b27…","approvedAt":"2026-11-14T08:14:17.327Z"},"config":{…},"sources":{"repo":"user","default_command":"repo","commands.dev":"user","commands.test":"repo","editor":"default",…}}
```

`approved` is `null` until you trust a `.testlane.toml`. `config` uses the TOML key names, and `sources` maps each dotted key, like `commands.dev` or `env.PORT`, to its source.

### `config trust <project>`

`config trust` shows the repository's `.testlane.toml` and records your approval, so its commands can run. It clones the repository if it isn't cloned yet and fetches the default branch. Then it shows the whole file the first time, or the diff from the version you approved, and asks.

```bash
testlane config trust my-project
```

When there's nothing to approve, it says so and exits `0`:

```
→ fetching origin/main
→ my-project:.testlane.toml is already trusted (sha256 b07a0b275b7f)
```

When the repository has no file, it prints `→ no .testlane.toml on origin/main` instead. With no terminal to ask on, pass `--yes` to approve. Without it, `config trust` shows the file, then exits `3` with the hint `re-run on a terminal, or pass --yes`. It doesn't take `--dry-run`. [Ship a config with your repo](https://testlane.dev/docs/guides/ship-a-config-with-your-repo#approve-it) explains what the trust check protects you from.

### `config detect`

`config detect` reads a repository's files and prints a draft project config, so you start from what the repository already says, like its package manager, its workspace packages and its dev servers, rather than from a blank file. It writes nothing and runs nothing from the repository: no install, no script. It only reads files.

```
testlane config detect [path | project] [--repo-file]
```

| Flag | What it does | Default |
| --- | --- | --- |
| `--repo-file` | Print only the keys a `.testlane.toml` may hold, without `repo` | Off |

The argument is a directory or a project. With none, it reads the current directory. An argument that holds a `/`, is `.` or `..`, or starts with `~` is a directory, read straight from disk with no git, so it works before the config directory exists. Anything else is a project, read from the default branch of its clone, `origin/main` for example, with no checkout and no fetch. To read a directory whose name looks like a project, write it as `./my-project`.

```bash
cd ~/code/my-project
testlane config detect
```

```toml
# note: drafted by testlane config detect from my-project/; review every line marked guess or note
# note: pnpm-workspace.yaml: skipped allowBuilds
repo = "git@github.com:ORG/REPO.git"  # guess: no repository URL found; replace it

[setup]
# note: the install runs package.json postinstall "nuxt prepare"
run = "pnpm install --frozen-lockfile"  # detected: packageManager is pnpm@10.33.4; frozen install of pnpm-lock.yaml
cache_key = ["pnpm-lock.yaml", "pnpm-workspace.yaml", "package.json"]  # detected: the lockfile and package.json
seed_files = [".env"]  # detected: .env.example; set seed_from in <project>.toml to a folder that holds the real files

[env]
NUXT_TELEMETRY_DISABLED = "1"  # detected: the root package runs Nuxt

[commands.dev]
run = "pnpm exec nuxt dev --host 127.0.0.1 --port {port}"  # detected: the root package dev runs nuxt and depends on it; the main app (the root package)

[commands.test]
run = "pnpm test"  # detected: package.json has a test script

[commands.check]
run = "pnpm check-types"  # detected: package.json scripts check-types
```

Every line says why it's there. `# detected:` is a fact read from a file, `# guess:` is a choice the files don't settle, and `# note:` is something the draft leaves to you, like a step it doesn't guess. It's best to read every guess and note before you use the draft. The draft follows these rules:

| What | Where it comes from |
| --- | --- |
| Package manager | The `packageManager` field, then the lockfile. With several lockfiles and no `packageManager`, a guess, with a note naming the others |
| `setup.run` | The package manager's frozen install, like `pnpm install --frozen-lockfile` or `npm ci`. With no lockfile, a plain `<pm> install`, as a guess |
| `setup.cache_key` | The lockfile, `pnpm-workspace.yaml` and the `package.json` files |
| Apps | Workspace packages with a `dev` script, from `pnpm-workspace.yaml` `packages:` or `package.json` `workspaces`. Packages under `apps/` come first, and a `dev` that calls `turbo`, `nx` or `vp` doesn't count |
| `commands.dev` | The main app, `apps/web`, then `apps/docs`, then the root. Each other app gets a command named after its package, `{port+1}` and on, and `ports` |
| Dev server | Nuxt, Next.js, Vite, Astro and Storybook get their own flags to bind `127.0.0.1:{port}`. Any other `dev` runs as it is, with `PORT` set, as a guess |
| Build before dev | With a `turbo.json`, a `turbo run build` of the main app's dependencies. With nx, lerna or vite-plus, a note and no guess |
| `setup.seed_files` | One file for each `.env*.example`, like `apps/web/.env` |
| `test` and `check` | The root `test` script, and the root `check` script, or else `lint`, `format:check` and `typecheck`. Yarn runs each with `yarn run`, since Yarn 1's own `yarn check` would win over a `check` script |
| `conductor.toml` | Its `setup` and `run` scripts, as notes |

Testlane checks the draft against the same rules as a project file before it prints it, so it always loads. Note that `seed_files` only names the files: set `seed_from` in your project file to a folder that holds the real ones. With `--json`, it prints one object with the draft and every finding:

```json
{"source":{"kind":"path","path":"/home/you/code/my-project"},"repoFile":false,"config":{"repo":"git@github.com:ORG/REPO.git","setup":{…},"env":{…},"commands":{…}},"findings":[{"key":"setup.run","value":"pnpm install --frozen-lockfile","kind":"detected","confidence":"high","reason":"packageManager is pnpm@10.33.4; frozen install of pnpm-lock.yaml"},…]}
```

A project's `source` is `{"kind":"project","project":"my-project","ref":"origin/main"}`. Each finding's `key` is a dotted key, like `commands.dev.run`, or `null` for a note. `kind` is `detected`, `guess` or `note`, and `confidence` is `high`, `medium` or `low`, where every guess is `low`.

`config detect` stops with these exit codes:

| Exit code | When |
| --- | --- |
| `2` | The directory doesn't exist, or the name isn't a project you've configured, with the hint `pass ./<name> for a directory` |
| `3` | The project isn't cloned yet, or its default branch isn't fetched. `testlane config trust <project>` does both |

## `completions`

`completions` prints a completion script for `bash`, `zsh` or `fish`, so your shell completes verbs, project names and workspace slugs.

```
testlane completions <bash|zsh|fish>
```

```bash
eval "$(testlane completions bash)"
```

The script holds the project names you had when you made it, so make it again after you add a project. Another shell exits `2`:

```
error(E_USAGE): unsupported shell 'ksh'
hint: one of: bash, zsh, fish
```

[Install shell completions](https://testlane.dev/docs/guides/shell-completions) shows where to put the script for each shell.

## `mcp`

`mcp` serves Testlane's tools to an AI agent over the Model Context Protocol (MCP), so the agent calls typed tools instead of reading the CLI's output. You don't run it yourself: your MCP client starts it and talks to it over stdin and stdout.

```
testlane [--config-dir <dir>] mcp
```

```bash
claude mcp add testlane -- testlane mcp
```

`mcp` takes no arguments and exits `2` when given any, while global flags like `--config-dir <dir>` still work before or after it. The server starts even when the config directory doesn't exist yet: `doctor` still works, and every other tool returns an `E_CONFIG` error until you create it.

Each tool calls the same code as its verb and returns that verb's `--json` output. [Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent#connect-over-mcp) lists the tools and what they return, [Agents](https://testlane.dev/docs/getting-started/agents#mcp) has the JSON config for other clients, and [ADR-003](https://github.com/uxfront-com/testlane/blob/main/docs/adrs/003-mcp-server.md) explains why we wrote the server by hand.

Note that a project named `mcp` can only be reached by its repository URL, like `testlane https://github.com/acme/mcp 42`, since the verb takes the name.

## `help` and `version`

`help` prints the grammar, every verb, the global flags and the order Testlane looks for its config directory in, and `version` prints the version.

```bash
testlane help
testlane version
```

```
testlane 2.0.0
```

Both always exit `0`. Note that they're verbs with no flag form, so `testlane help` is the way to get the usage text.
