Configuration and environment variables
Reference for Qualflare CLI settings: every QF_* environment variable and its default, the global flags, CI branch and commit detection, and which setting wins.
Last updated
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:
- Command-line flags (e.g.,
--environment,--branch) - Environment variables (e.g.,
QF_ENVIRONMENT,QF_BRANCH) - The report file: the environment and platform a native reporter wrote into its report
- Auto-detection: CI platform variables, then the local git checkout (branch and commit only)
- Built-in defaults
Authentication is separate from this priority chain — credentials are stored per-identifier in a local config file by qf login.
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.
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. |
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 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.
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. qf ≥ 0.7.0 (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_BRANCHCommit detection
The CLI checks these variables in order, using the first non-empty value:
QF_COMMIT → GIT_COMMIT → GITHUB_SHA → CI_COMMIT_SHA → BITBUCKET_COMMITIf 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 · Authenticate with qf login · CI/CD Integration
- Reference: Upload results with qf collect · Upload screenshots, videos and traces · Troubleshoot qf and CI uploads · Access Tokens
- Changelog: qf 0.1.9: no more false-green uploads, plus debug and privacy flags · What's new in Qualflare: May 2026
Sharded runs and result directories
Upload sharded or parallel CI test runs to Qualflare as one launch with qf collect: result directories, run selection, --allow-mixed-runs and --shard.
qf command reference
Every qf command in the Qualflare CLI, with flags, output and exit codes: validate result files without a token, list the formats and print the version.