# 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

| Aspect           | Configuration                                                                        |
| ---------------- | ------------------------------------------------------------------------------------ |
| 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 names    | Lower-case letters, digits, `.`, `_` and `-`, starting with a letter or a digit, but not `defaults` or `seeds` |
| Create one       | `testlane setup` for your first project, `testlane config add <project>` or `testlane config add <url>` after that |
| Check it         | `testlane 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:

```bash
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](https://testlane.dev/docs/guides/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:

```toml [~/.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
```

| Key               | What it's for                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `root`            | Where a project's clone and workspaces go by default: `{root}/{project}/repo` and `{root}/{project}/trees` |
| `editor`          | A preset name or a template, as on [Editors](https://testlane.dev/docs/configuration/editors). Without one, it's `code`                   |
| `default_command` | A verb or a command name, as on [Commands and Hooks](https://testlane.dev/docs/configuration/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](https://testlane.dev/docs/guides/ship-a-config-with-your-repo) walks through it, and [Commands and Hooks](https://testlane.dev/docs/configuration/commands-and-hooks#from-the-repository) 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:

```bash
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>`](https://testlane.dev/docs/cli/top-level-verbs#config-add-url) has the details.

To check every file at once, run `config validate`:

```bash
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](https://testlane.dev/docs/configuration/environment-and-templates) has the rules.

## Where to go next

::card-group

::card{title="Project File" icon="i-lucide-file-code" to="/docs/configuration/project-file"}
Every key a project file takes, with its type and default.
::

::card{title="Commands and Hooks" icon="i-lucide-play" to="/docs/configuration/commands-and-hooks"}
Named commands for `run` and `start`, and the four lifecycle hooks.
::

::card{title="Environment and Templates" icon="i-lucide-braces" to="/docs/configuration/environment-and-templates"}
The `{port}` family of template variables and the `TESTLANE_*` environment.
::

::card{title="Editors" icon="i-lucide-app-window" to="/docs/configuration/editors"}
Editor presets and templates of your own.
::

::card{title="Ship a Config with Your Repo" icon="i-lucide-package-check" to="/docs/guides/ship-a-config-with-your-repo"}
Commit a `.testlane.toml`, so everyone who adds the project gets working setup and commands.
::

::
