CLI Reference

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

VerbWhat it does--json
setupCreates the config directory and your first project fileNo
projectsLists the projects you've configuredYes
doctorChecks your machine and every project fileYes
configPrints, opens, checks, shows or trusts the config files, adds a project from its repository and drafts a config from a repository's filesconfig validate, config show and config detect
completionsPrints a completion script for your shellNo
mcpServes Testlane's tools to an AI agent over MCPNo
help and versionPrints the usage text or the versionNo

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]
FlagWhat it doesDefault
--name <name>The project's name, and the name of its file, <name>.tomlAsked for
--repo <url>The repository to clone, written as repoAsked 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 againstNone
--forceOverwrite the project file when it exists alreadyOff
--detectClone the repository and, when it has no .testlane.toml, write a config drafted from its files, as config detect doesOff

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 codeWhen
2The name isn't valid, the repository is empty or a value is missing with no terminal to ask on
3The 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 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 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]
SubcommandWhat it does
pathPrints 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]
FlagWhat it doesDefault
--name <name>The project's name, and the name of its fileThe repository's name
--root <dir>The base directory for clones and workspaces, written to defaults.toml as root, for a new machineThe root in defaults.toml
--detectWhen the repository has no .testlane.toml, start the file from a config drafted from its files instead of the starter fileOff

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 does.
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 codeWhen
2The 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
3There's no terminal to ask on and no --yes. The project stays added, and the hint is testlane config trust <name>
5The 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]
FlagWhat it doesDefault
--repo-filePrint only the keys a .testlane.toml may hold, without repoOff

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:

WhatWhere it comes from
Package managerThe packageManager field, then the lockfile. With several lockfiles and no packageManager, a guess, with a note naming the others
setup.runThe 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_keyThe lockfile, pnpm-workspace.yaml and the package.json files
AppsWorkspace 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.devThe 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 serverNuxt, 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 devWith 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_filesOne file for each .env*.example, like apps/web/.env
test and checkThe 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.tomlIts 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 codeWhen
2The directory doesn't exist, or the name isn't a project you've configured, with the hint pass ./<name> for a directory
3The 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.

Copyright © 2026