Configuration

Overview

Where Testlane keeps your project files, what goes in the config directory, what a repository's own .testlane.toml adds, and how to create, edit and check a project.

Your configuration tells Testlane how to turn any ref of a project into a workspace you can run: which repository to clone, how to install it, which ports it gets and what to start. It's one TOML file per project in a config directory of its own, ~/.testlane by default, so you never have to add anything to your repository. A repository can still ship a .testlane.toml with its setup, env and commands, which you approve once and your own file overrides.

This page covers:

  • Where the config lives: how Testlane picks its config directory.
  • What's inside it: the project files, defaults.toml and the seed files.
  • Defaults for every project: the three keys defaults.toml takes.
  • A repository's own file: what a .testlane.toml in the repository adds, and how it's kept safe.
  • Create, edit and check a project: the config verbs.

At a glance

AspectConfiguration
Where it lives--config-dir, then $TESTLANE_CONFIG_DIR, then ~/.testlane
One project<config-dir>/<project>.toml, where the file name is the project's name
Shared defaults<config-dir>/defaults.toml, with root, editor and default_command
Seed files<config-dir>/seeds/<project>/
A repository's file.testlane.toml at the repository's root, read from the default branch once you trust it
Project namesLower-case letters, digits, ., _ and -, starting with a letter or a digit, but not defaults or seeds
Create onetestlane setup for your first project, testlane config add <project> or testlane config add <url> after that
Check ittestlane config validate, which exits 3 (E_CONFIG) on any error

Where the config lives

Let's start with where Testlane looks. It takes the first of these that's set:

  1. The --config-dir flag.
  2. The TESTLANE_CONFIG_DIR environment variable.
  3. ~/.testlane.

testlane config path prints the directory it picked, which is handy when you're not sure which one a script sees:

testlane config path
/home/you/.testlane

If the directory doesn't exist, most verbs stop with E_CONFIG and exit 3, with a hint to create it. setup and config add <url> --root <dir> create it for you, and help, version, doctor, completions, mcp and config path run without it.

What's inside it

Now let's look at what goes in the directory. Each project is one TOML file named after the project, next to an optional defaults.toml and a seeds directory for files you want copied into new workspaces:

<config-dir>/
  defaults.toml            # optional, shared by every project
  my-project.toml          # one file per project, named after it
  seeds/
    my-project/            # seed files for "my-project"
      .env.local

A project's name is its file name without .toml. It must match ^[a-z0-9][a-z0-9._-]*$, and defaults and seeds are taken, so Testlane ignores files with those names when it lists your projects. Seed local files walks through the seeds directory.

Defaults for every project

Next, let's look at defaults.toml. It takes three optional keys, and a project file that sets the same key wins:

~/.testlane/defaults.toml
root = "~/dev/testlane"     # where repo_path and worktrees_path go when a project doesn't set them
editor = "zed"              # the editor for projects that don't set one
default_command = "code"    # what `testlane <project> <ref>` does when a project doesn't say
KeyWhat it's for
rootWhere a project's clone and workspaces go by default: {root}/{project}/repo and {root}/{project}/trees
editorA preset name or a template, as on Editors. Without one, it's code
default_commandA verb or a command name, as on Commands and Hooks. Without one, it's code

Any other key is an error, env and commands included. We keep them out of defaults.toml on purpose, since they belong to one project: in its project file, or in its repository's .testlane.toml.

A repository's own file

Then let's look at the file a repository can ship. A .testlane.toml at the repository's root lets its maintainers write its setup, env and commands once, so you don't have to:

<repository>/
  .testlane.toml           # optional, read from origin/<default> once you trust it

It holds only what describes the repository. The keys about your machine, like repo_path or editor, stay in your project file, and Testlane rejects them in the repository's file. Where a key is in both files, yours wins, and testlane config show <project> prints the merged config with where each key came from.

Testlane reads the file only from the tip of the default branch, never from the branch or pull request you check out, so a pull request can't change what runs on your machine. It runs the file's commands only after you approve that exact content, and asks again whenever it changes. Ship a config with your repo walks through it, and Commands and Hooks gives the merge rules.

Create, edit and check a project

Finally, let's look at the config verbs. setup asks for a project's name and repository and writes your first project file, along with a defaults.toml that sets root when it isn't set yet. After that, config add creates a new project file from a starter template and opens it:

testlane setup                       # create the config directory and your first project
testlane config add my-project       # create a project file and open it
testlane config add https://github.com/my-org/my-project   # add a project from its repository
testlane config edit my-project      # open a project file
testlane config edit                 # open the config directory

add and edit do the same thing: each opens the project's file, and creates it from the template first when it isn't there. The starter file sets only repo, with the other common keys commented out, so it's ready once you swap in your repository's URL. An existing project opens in the project's own editor, and a new one in $VISUAL or $EDITOR, then vi.

Give config add a repository's URL instead, and it names the project after the repository, writes its repo line, clones it and asks you to trust the repository's .testlane.toml. Without one, it opens the starter file as above. config add <url> has the details.

To check every file at once, run config validate:

testlane config validate
→ all project configs valid

Pass a project's name to check only its file. Testlane reports every problem in a file in one run, rather than stopping at the first, and exits 3 (E_CONFIG) when it finds any:

my-project.toml: ports: Number must be less than or equal to 10
my-project.toml: (root): Unrecognized key(s) in object: 'worktree_path'

Without a project's name, --json prints the result for scripts and CI, as an object with ok and an issues list, where each issue has a file, a path and a message. Keep in mind that template variables are checked when a command uses them rather than here, so a {port+1} in a project with one port only fails when that workspace runs. Environment and Templates has the rules.

Where to go next

Project File

Every key a project file takes, with its type and default.

Commands and Hooks

Named commands for run and start, and the four lifecycle hooks.

Environment and Templates

The {port} family of template variables and the TESTLANE_* environment.

Editors

Editor presets and templates of your own.

Ship a Config with Your Repo

Commit a .testlane.toml, so everyone who adds the project gets working setup and commands.
Copyright © 2026