# Global Flags

> The flags every Testlane command takes, for the config directory, the kind of ref, dry runs, JSON output, how much it logs and prompts.

Global flags change how any command behaves rather than what it does: which config it reads, how it reads the ref, whether it changes anything and what it prints. You can put them anywhere before `--`, so `testlane --json my-project list` and `testlane my-project list --json` do the same.

## At a glance

| Flag | What it does | Applies to |
| --- | --- | --- |
| `--config-dir <dir>` | Read the config from this directory | Every command |
| `--pr <n>`, `--branch <name>`, `--path <p>` | Read the ref as this kind, in place of the ref | Workspace commands |
| `--dry-run` | Print what would run, and change nothing | Every command that changes something |
| `--json` | Print one JSON document on stdout | `checkout`, `list`, `info`, `start`, `ps`, `projects`, `doctor`, `config validate`, `config show` and `config detect` |
| `-q`, `--quiet` | Leave out the `→` step lines | Every command |
| `-v`, `--verbose` | Also print every external command, and the stack trace of an error | Every command |
| `-y`, `--yes` | Answer yes to every prompt, and approve a repository's config | `clean`, `rm`, `setup`, `config add`, `config trust` and every command that checks a repository's config |
| `--no-color` | Print no colours | Every command |

## `--config-dir`

`--config-dir <dir>` points Testlane at another config directory for one command, like a test setup or a CI checkout. Testlane looks for the directory in this order, and takes the first one it finds:

1. `--config-dir <dir>`.
2. `$TESTLANE_CONFIG_DIR`.
3. `~/.testlane`, which `setup` creates.

```bash
testlane --config-dir ./ci-config projects
```

`testlane config path` prints the directory that won.

## `--pr`, `--branch` and `--path`

These three tell Testlane what kind of ref you mean, for the names it could read two ways, like a branch called `42`. Each one takes the ref as its value and replaces the ref in the command:

```bash
testlane my-project --branch 42 checkout    # a branch named "42"
testlane my-project --pr 42 info            # PR 42
testlane my-project --path ./hotfix shell   # a working tree you already have
```

You can give one of them at a time, and only to a workspace command. Anything else exits `2`. [Refs](https://testlane.dev/docs/concepts/refs) explains how Testlane reads a ref without them.

## `--dry-run`

`--dry-run` shows what a command would do and changes nothing: it prints the commands it would run on stdout, one per line, takes no locks and asks no questions.

```bash
testlane my-project feat/login sync --discard --dry-run
```

```
git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options feat/login
git -C /home/you/dev/testlane/my-project/trees/feat-login reset --hard HEAD
git -C /home/you/dev/testlane/my-project/trees/feat-login clean -fd
git -C /home/you/dev/testlane/my-project/trees/feat-login reset --hard @{u}
```

`run`, `exec`, `shell` and `start` also print the environment the command would get, as `export` lines, then the command itself. `setup` prints the files it would write, and `clean` and `rm` print their plan.

## `--json`

`--json` replaces the normal output with one JSON document on stdout, for scripts. Progress, warnings and what `[setup]` and hooks print all stay on stderr, so `$(testlane … --json)` captures clean JSON.

```bash
testlane my-project feat/login info --json
```

`checkout`, `list`, `info`, `start`, `ps`, `projects`, `doctor` and `config validate` support it, and each verb's section lists its fields. `code` exits `2` with it. The other verbs print no JSON, but `--json` still sends what `[setup]` and hooks print to stderr, so stdout holds only the verb's own output. That's why [Use Testlane from an agent](https://testlane.dev/docs/guides/use-testlane-from-an-agent) passes it to `rm`. [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) shows what you can build on it.

## `--quiet` and `--verbose`

These two set how much Testlane says on stderr. `-q` leaves out the `→` step lines, so only the result is left. Warnings and errors still print:

```bash
testlane my-project feat/login checkout -q
```

```
/home/you/dev/testlane/my-project/trees/feat-login
```

`-v` adds a line starting with `·` for every external command Testlane runs, so you can see what it does for you:

```
→ fetching origin/main
· git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options main
· git -C /home/you/dev/testlane/my-project/repo worktree add /home/you/dev/testlane/my-project/trees/main -B main --track origin/main
→ worktree ready: /home/you/dev/testlane/my-project/trees/main
/home/you/dev/testlane/my-project/trees/main
```

With `-v`, an error also prints its stack trace, which is what to attach to a bug report. Setting `TESTLANE_DEBUG=1` does the same without the extra lines.

## `--yes`

`-y` answers yes to every prompt, for scripts and CI. `clean` and `rm` need it when there's no terminal to ask on, and exit `2` without it. `setup` takes the default root, `~/dev/testlane`, instead of asking for it.

It also approves a repository's `.testlane.toml` when the trust check would ask. Testlane still prints the file, or the diff since you last trusted it, then records the approval without a question, so read what it prints in a script's log. [Ship a config with your repo](https://testlane.dev/docs/guides/ship-a-config-with-your-repo) explains the trust check.

## `--no-color`

`--no-color` turns colours off. Testlane also leaves them out when `$NO_COLOR` is set, or when stderr isn't a terminal, like when you pipe it to a file.
