# Configuration and environment variables

Source: https://docs.qualflare.com/docs/cli/configuration · Last updated: 2026-11-21

Reference for Qualflare CLI settings: every QF_* environment variable and its default, the global flags, CI branch and commit detection, and which setting wins.

This page lists every setting of the Qualflare CLI (`qf`): the `QF_*` environment variables and their defaults, such as `development` for `QF_ENVIRONMENT`, the global flags, and CI auto-detection. A flag beats an environment variable, which beats the report file, auto-detection and the built-in defaults.

## Configuration priority

Highest to lowest:

1. **Command-line flags** (e.g., `--environment`, `--branch`)
2. **Environment variables** (e.g., `QF_ENVIRONMENT`, `QF_BRANCH`)
3. **The report file**: the environment and platform a native reporter wrote into its report
4. **Auto-detection**: CI platform variables, then the local git checkout (branch and commit only)
5. **Built-in defaults**

Authentication is separate from this priority chain — credentials are stored per-identifier in a local config file by [`qf login`](https://docs.qualflare.com/docs/cli/authentication).

## Authentication

`qf` keeps credentials apart from these settings: `qf login <identifier>` signs in (or saves a project access token) under a local identifier, and `QF_TOKEN` is read only by `qf login`. Token sources, identifier rules, the credentials file and CI setup are in [Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication).

## Global flags

These flags are available on every `qf` command:

| Flag                  | Short | Type | Default | Env Var                | Description                                                               |
| --------------------- | ----- | ---- | ------- | ---------------------- | ------------------------------------------------------------------------- |
| `--verbose`           | `-v`  | bool | `false` | `QF_VERBOSE`           | Enable verbose debug output.                                              |
| `--quiet`             | `-q`  | bool | `false` | `QF_QUIET`             | Suppress all non-error output.                                            |
| `--debug`             |       | bool | `false` | `QF_DEBUG`             | Log full HTTP request/response detail to stderr (token redacted).         |
| `--no-capture-output` |       | bool | `false` | `QF_NO_CAPTURE_OUTPUT` | Strip captured stdout/stderr and custom test properties before uploading. |

## Environment variables

All environment variables can be set in your shell profile, `.env` file, or CI/CD secrets.

### Test run metadata

| Variable              | Default              | Description                                                                                                                                                                                                                                        |
| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `QF_ENVIRONMENT`      | `development`        | Identifier of the environment the tests ran against. It must already exist in the project (**Settings** → **Environments**). New projects have `development`, `staging`, `production` and `qa`.                                                    |
| `QF_LANGUAGE`         | `en-US`              | Language of the launch, as a language tag Qualflare supports (e.g., `en-US`, `de-DE`). An unsupported tag fails the upload.                                                                                                                        |
| `QF_PLATFORM`         | `api`                | Platform the tests ran on. One of `android`, `ios`, `desktop`, `web`, `api`.                                                                                                                                                                       |
| `QF_BRANCH`           | *Auto-detected*      | Git branch name. Auto-detected from CI environment if not set.                                                                                                                                                                                     |
| `QF_COMMIT`           | *Auto-detected*      | Git commit SHA. Auto-detected from CI environment if not set.                                                                                                                                                                                      |
| `QF_MILESTONE`        | *(none)*             | Milestone sequence number to link the launch to. Values below `1` are ignored, and the milestone must exist in the project.                                                                                                                        |
| `QF_UPLOAD_ARTIFACTS` | *(screenshots only)* | Artifact kinds `collect` uploads in addition to screenshots: `video`, `trace`. `image` (screenshots) is accepted and already on. Set `none` to upload no artifacts. Same as [`--upload-artifacts`](https://docs.qualflare.com/docs/cli/artifacts). |

### Retry & timeout

| Variable             | Default | Description                                                                                                                                                                                                                                                                          |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `QF_RETRY_MAX`       | `3`     | Maximum number of retry attempts (capped at 10).                                                                                                                                                                                                                                     |
| `QF_RETRY_DELAY`     | `1s`    | Base delay between retries (exponential backoff).                                                                                                                                                                                                                                    |
| `QF_RETRY_MAX_DELAY` | `30s`   | Maximum delay between retries.                                                                                                                                                                                                                                                       |
| `QF_TIMEOUT`         | `120s`  | Timeout for each HTTP request attempt, and the overall deadline for read commands such as `suites list`. Go duration, e.g. `500ms`, `60s`, `2m`. The overall deadline of `collect` is its [`--timeout`](https://docs.qualflare.com/docs/cli/collect#--timeout) flag (default `30s`). |

### Output

| Variable     | Default | Description                                        |
| ------------ | ------- | -------------------------------------------------- |
| `QF_VERBOSE` | `false` | Set to `true` or `1` to enable verbose output.     |
| `QF_QUIET`   | `false` | Set to `true` or `1` to suppress non-error output. |

`QF_TOKEN` is read only by `qf login`: see [Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication#log-in-in-ci).

### Plan limits

| Variable                | Default | Description                                                                                                                                                                                                                                                                    |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `QF_WARN_ON_PLAN_LIMIT` | `false` | Set to `true` or `1` so that `collect` warns and exits `0` instead of `4` when a plan limit refuses the upload. The results are not uploaded. Same as [`--warn-on-plan-limit`](https://docs.qualflare.com/docs/cli/collect#--warn-on-plan-limit). (requires qf 0.7.0 or later) |

## CI auto-detection

In CI environments, the CLI automatically detects git metadata from well-known environment variables. Manual flags and `QF_*` variables always override auto-detection.

### Branch detection

The CLI checks these variables in order, using the first non-empty value:

```
QF_BRANCH → GIT_BRANCH → GITHUB_REF_NAME → CI_COMMIT_REF_NAME → BITBUCKET_BRANCH
```

### Commit detection

The CLI checks these variables in order, using the first non-empty value:

```
QF_COMMIT → GIT_COMMIT → GITHUB_SHA → CI_COMMIT_SHA → BITBUCKET_COMMIT
```

If none of these is set, `collect` reads the branch and commit from the local git checkout. A detached HEAD, which many CI checkouts use, gives no branch, so set `QF_BRANCH` or pass `--branch` there.

## Related

* **Guides:** [Install the CLI](https://docs.qualflare.com/docs/cli/installation) · [Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication) · [CI/CD Integration](https://docs.qualflare.com/docs/cli/ci-cd)
* **Reference:** [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Upload screenshots, videos and traces](https://docs.qualflare.com/docs/cli/artifacts) · [Troubleshoot qf and CI uploads](https://docs.qualflare.com/docs/cli/troubleshooting) · [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens)
* **Changelog:** [qf 0.1.9: no more false-green uploads, plus debug and privacy flags](https://changelog.qualflare.com/qf-cli-reliability-release) · [What's new in Qualflare: May 2026](https://changelog.qualflare.com/may-2026)
