Top-Level Verbs
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 | Creates the config directory and your first project file | No |
projects | Lists the projects you've configured | Yes |
doctor | Checks your machine and every project file | Yes |
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 | Prints a completion script for your shell | No |
mcp | Serves Testlane's tools to an AI agent over MCP | No |
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 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:
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> does, and the project file stays as written. When there's none, it writes the draft from 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.
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:
[{"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.
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
ghis 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.hooksPaththat 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 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> | 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> | Prints the config a run would use, and where each key came from |
trust <project> | Shows the repository's .testlane.toml, and records your approval |
detect [path | project] | Prints a config drafted from a repository's files |
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 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 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:
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:
- It names the project after the repository, like
my-project, unless you pass--name. - It writes
<name>.tomlwith one line,repo = "<clone url>": an ssh URL as you gave it, orhttps://<host>/<owner>/<repo>.git. - It clones the repository.
- It shows the repository's
.testlane.tomland asks you to trust it, asconfig trustdoes.
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 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:
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:
{"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.
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 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.
cd ~/code/my-project
testlane config detect
# 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:
{"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>
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 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
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 lists the tools and what they return, Agents has the JSON config for other clients, and ADR-003 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.
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.