Configuration

Commands and Hooks

Name the commands you run in every workspace, like your dev server and your tests, hook your own scripts into a workspace's life, and merge them with a repository's .testlane.toml.

Named commands let you start the same thing in any workspace with one word, like run dev for your dev server or run test for your tests, with the right directory and environment every time. Hooks run your own scripts at four points in a workspace's life, so you can start a database before a command or stop a container before a removal. A repository can ship both in its .testlane.toml, and yours win over its.

At a glance

KeyTypeDefaultWhat it's for
commands.<name>.runstringRequiredThe command run <name> and start <name> run
commands.<name>.cwdstringThe workspaceThe directory to run it in, relative to the workspace
commands.<name>.envtable{}Environment variables for this command only, over the project's [env]
default_commandstringcodeWhat testlane <project> <ref> does with no verb
hooks.post_checkoutstringNoneRuns once, after Testlane creates a workspace
hooks.pre_runstringNoneRuns after setup, before run, exec, shell and start
hooks.post_syncstringNoneRuns after sync resets a workspace
hooks.pre_cleanstringNoneRuns before rm or clean removes a workspace, and can stop the removal

A repository's .testlane.toml may set every key in this table, as From the repository explains.

Named commands

Each table under [commands] becomes something run and start can run, by its name:

~/.testlane/my-project.toml
[commands.dev]
run = "pnpm dev"
cwd = "packages/app"

[commands.dev.env]
NODE_OPTIONS = "--max-old-space-size=8192"

[commands.test]
run = "pnpm test"
testlane my-project 42 run dev
testlane my-project 42 run test -- --watch

A command's name also works in place of a verb, so testlane my-project 42 dev does what run dev does.

KeyWhat it doesDefault
runThe command, run with bash -c. It's requiredNone
cwdThe directory to run it in, relative to the workspace unless it's absoluteThe workspace
envVariables merged over the project's [env] for this command only{}

A command's name is lower-case letters, digits, :, _ and -, starting with a letter or a digit, like dev, test:e2e or storybook. run, cwd and the values in env can use template variables, like {port}.

Arguments after -- go on the end of the command, quoted as you typed them. run test -- --watch runs this:

bash -c 'pnpm test "$@"' testlane --watch

When you name a command after a workspace verb, like start or sync, the verb wins, so testlane my-project 42 start runs the verb. Your command is still there as testlane my-project 42 run start, and testlane doctor warns about the clash.

Default command

default_command says what Testlane does when you give it a project and a ref with no verb. It's code unless defaults.toml or the project file says otherwise:

~/.testlane/my-project.toml
default_command = "dev"

With that, testlane my-project 42 does what testlane my-project 42 run dev does. It takes one of the verbs checkout, code, shell, diff and info, or the name of one of the project's commands, and config validate rejects anything else:

my-project.toml: default_command: unknown command 'run'; expected a verb or one of [dev]

Hooks

Hooks are scripts of your own that Testlane runs at four points in a workspace's life. Each is a string, run with bash -c in the workspace, with the project's environment, TESTLANE_* variables included, and with template variables filled in:

~/.testlane/my-project.toml
[hooks]
post_checkout = "echo 'workspace ready: {path}'"
pre_run = "docker compose up -d"
post_sync = "pnpm install --frozen-lockfile"
pre_clean = "docker compose down"
HookWhen it runsIf it exits non-zero
post_checkoutOnce, after Testlane creates a workspace and before setupThe command fails with E_SETUP, exit 6
pre_runAfter setup, before run, exec, shell and startThe command fails with E_SETUP, exit 6
post_syncAfter sync resets a workspaceTestlane warns and carries on
pre_cleanBefore rm or clean removes a workspaceTestlane warns and keeps that workspace

We recommend keeping hooks fast and safe to run twice, since pre_run runs before every run, exec, shell and start. There are two exceptions: --no-setup skips it along with setup, and so does a start that finds its command already running.

When post_checkout fails, Testlane keeps the workspace but doesn't run the hook for it again. To run it again once you've fixed it, remove the workspace with rm and open it again.

pre_clean is the place to let go of what a workspace held, like a container or a scratch database, since its directory is gone after the removal. A failing pre_clean keeps that workspace, so you can also use it to stop a removal:

warning: pre_clean hook failed for feat-login — skipping

--dry-run on rm and clean prints pre_clean as the bash -c line it would run, and runs nothing.

From the repository

A repository's .testlane.toml can define [commands] and [hooks] too, so its maintainers set them up once for everyone. They join your own, and your project file wins:

TableHow the two files merge
[commands]By name. A command of yours replaces the whole repository command of that name, cwd and env included
[hooks]By hook name. Your pre_run replaces the repository's pre_run, and its other hooks still run
[env]By key

So to change how the repository's dev runs on your machine, define your own [commands.dev]. It's best to copy the repository command's cwd and env into yours if you still need them, since none of the repository's command is kept:

~/.testlane/my-project.toml
[commands.dev]
run = "pnpm dev --port {port} --open"

testlane config show my-project marks each key with where it came from. Here's an excerpt:

default_command = "dev"                             # repo
commands.dev.run = "pnpm dev --port {port} --open"  # user
commands.test.run = "pnpm test"                     # repo
hooks.post_checkout = "echo ready: {path}"          # repo

Trust them first

A repository's file can run anything your shell can, so its commands, hooks and setup run only after you approve that exact content. The first time, Testlane prints what the file would run, then the whole file:

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]

After a change upstream, it prints the diff from the version you approved and asks again. --yes approves without asking. With no terminal to ask on and no --yes, the command stops with exit 3:

error(E_CONFIG): my-project:.testlane.toml is not trusted
hint: testlane config trust my-project

Until you approve, your project file works on its own, and the repository's commands don't exist yet, so testlane my-project 42 run dev fails with unknown command 'dev'. Run testlane config trust my-project first. Ship a config with your repo covers trust in full.

The order things run in

Here's what testlane my-project 42 run dev does on a ref with no workspace yet:

Create the workspace

Testlane resolves the ref and fetches it, checks the repository's .testlane.toml against your approval, then adds the worktree, ports and data directory.

Run post_checkout

It runs only this once, for a new workspace.

Run setup

Testlane copies the seed files in, then runs setup.run when the files in cache_key have changed. --no-setup skips this step and the next one.

Run pre_run

It runs before every command, as long as setup ran.

Run the command

Last, Testlane runs commands.dev.run.

On a workspace that's already there, Testlane starts at setup, which is usually a cache hit:

→ worktree ready (reused)
→ setup up to date (cache hit)
→ hook pre_run

FAQ

Copyright © 2026