Configuration

The Qualflare CLI (qf) is configured through command-line flags and environment variables. Flags always take precedence over environment variables, which take precedence over auto-detection and defaults.

Configuration Priority

Highest to lowest:

1. Command-line flags (e.g., --environment, --branch)
2. Environment variables (e.g., QF_ENVIRONMENT, QF_BRANCH)
3. Auto-detection (Git metadata, CI platform variables)
4. Built-in defaults

Authentication is separate from this priority chain — credentials are stored per-identifier in a local config file by qf login.

Authentication

The CLI uses a project-identifier model: you save a token under a short local alias, then prefix every project command with that alias.

Getting a Token

Open Project → Settings → Access Tokens in the Qualflare dashboard and create a new token. Copy it immediately — tokens are shown only once.

qf login

qf login <identifier> <token>

Saves <token> under <identifier> in the local credentials file. After this, run project commands as qf <identifier> <command>.

# Save credentials for a project
qf login myapp qf_your_token_here

# Upload results
qf myapp collect results.xml

# In CI/CD, use --force to skip the interactive overwrite prompt
qf login ci "$QF_TOKEN" --force
qf ci collect test-results/*.xml

Identifier rules: lowercase letters, digits, hyphens, and underscores; 1–63 characters; must start with a letter or digit (e.g., my-app, ci, prod). Reserved names (login, logout, projects, version, and a few others) cannot be used as identifiers.

--force skips the confirmation prompt when an identifier already exists. Use it in CI to ensure the token is always current.

qf logout

qf logout <identifier>

Removes saved credentials for <identifier>. The identifier subcommand will no longer be available until you qf login again.

qf projects

qf projects

Lists all saved project identifiers. Useful for confirming what is currently configured.

Credentials File

Tokens are stored in:

• Linux: ~/.config/qualflare/config.toml
• macOS: ~/Library/Application Support/qualflare/config.toml
• Custom: $XDG_CONFIG_HOME/qualflare/config.toml if XDG_CONFIG_HOME is set

The file is created with permissions 0600. Treat it like an SSH private key — do not commit it or share it.

TIP

In CI environments, prefer running qf login ci "$QF_TOKEN" --force at the start of your job rather than mounting the credentials file. See CI/CD Integration for platform-specific examples.

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.

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	staging	Environment name for the test run (e.g., staging, production).
QF_LANGUAGE	en-US	Language code for test result labels (BCP 47 format, e.g., en-US, de-DE).
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.

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	30s	HTTP request timeout. Valid units: s, m.

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.

TIP

There is no QF_TOKEN environment variable read by the CLI for authentication. In CI, supply the token by running qf login <id> "$YOUR_SECRET" --force at the start of the job.

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

See Also

• Collect Command — Upload test results
• CI/CD Integration — Platform-specific setup guides
• Installation — Install the CLI
• Access Tokens — Create and manage project tokens