Configuration

Drift is flexible: you can configure the engine and its plugins via command-line parameters, environment variables, or configuration files (TOML, YAML, JSON, INI, JSON5, or RON).

Configuration Priority

If a value is defined in multiple places, Drift uses this precedence order:

Command-line parameters (highest priority)
Environment variables
Configuration files (lowest priority)

Configuration Files

Drift supports these configuration file formats:

TOML: drift.config.toml (Tom's Obvious Minimal Language)
YAML: drift.config.yaml (YAML Ain't Markup Language)
JSON: drift.config.json (JavaScript Object Notation)
INI: drift.config.ini (Windows INI format)
JSON5: drift.config.json5 (JSON for Humans)
RON: drift.config.ron (Rusty Object Notation)

Search Order

Drift searches for configuration files in the following order (for any supported format above):

OS Config Directory
- Linux: $XDG_CONFIG_HOME or $HOME/.config/drift.config.{ext}
- macOS: $HOME/Library/Application Support/drift.config.{ext}
- Windows: %APPDATA%\drift.config.{ext}
User Home: $HOME/.drift/drift.config.{ext}
Application Home: The home_dir identified in the next section

Example Configuration File (TOML)

log_level = "info" # default the logging to INFO level
plugin_dir = "~/.drift/plugins" # override directory where the plugins are installed

[log_filters]
hyper_util = "info"
wasmtime_wasi = "info"

[plugin_config.json]
content_types = ["application/thrift"]

The Application Home Directory (`home_dir)`

The home_dir is the central location where Drift looks for executables, plugins, and configuration files. It is determined in the following order:

The --drift-home-dir command-line parameter
The DRIFT_HOME_DIR environment variable
The directory where the Drift executable is run from
The current working directory

Environment Variables

Any simple, non-collection configuration value can be specified as an environment variable using the prefix DRIFT_ followed by the setting name in SCREAMING_SNAKE_CASE.

Example: To set the logging level, use DRIFT_LOG_LEVEL=DEBUG.

PactFlow Authentication (Required)

Drift requires authentication to PactFlow or a Pact Broker to manage contracts and test workflows. Set these credentials as environment variables:

# PactFlow (recommended)
export PACTFLOW_BASE_URL="https://your-workspace.pactflow.io"
export PACTFLOW_TOKEN="your-api-token"

# Legacy Pact Broker
export PACT_BROKER_BASE_URL="https://your-broker.example.com"
export PACT_BROKER_TOKEN="your-token"

Where to get your token:

PactFlow: Navigate to Settings → API Tokens in your workspace
Pact Broker: Contact your broker administrator for API token details

Token types:

Read-only tokens: Suitable for local development and CI/CD pipelines that only read contracts
System account tokens: For CI/CD pipelines that publish contracts; requires appropriate permissions

See Authentication for more details on token types and PactFlow documentation for roles and permissions.

Core Configuration Values

Value	Default	Description
`log_level`	`INFO`	The logging level: TRACE, DEBUG, INFO, WARN, ERROR.
`log_filters`	N/A	Filter log entries based on target or spans.
`home_dir`	See Section 3	Drift application home directory.
`output_dir`	N/A	Directory where output files (like reports) are written.
`plugin_dir`	`home_dir/plugins`	Directory where plugins are loaded from.
`core_plugins`	N/A	A list of plugins that are always loaded automatically.
`servers`	N/A	Server authentication configuration (see Section 7).

Plugin Directory Logic

If not explicitly configured, the plugin_dir defaults to a folder named plugins within your home_dir. This is where standard plugins (OAS, JSON, Data, etc.) are expected to reside.

drift component installs plugins into the same directory. To install into a different directory, pass --plugin-dir or set the DRIFT_PLUGIN_DIR environment variable. To check which directories Drift resolved, run drift component info <name> --paths.

Server Authentication for Remote Sources

Drift allows you to manage credentials for remote URIs outside of your testcase files for improved security.

Using a Configuration File

Define server credentials in your config file. Drift uses a longest-match algorithm to find the correct credentials based on the source URL.

[servers.0]
url = "http://localhost:8000"
username = "lloyd"
secret = "chimps"

[servers.1]
url = "http://localhost:8000/secret"
username = "lloyd2"
secret = "monkeys"

Each server entry supports:

url (required): The base URL for the server
scheme: Authentication scheme - basic (default), bearer, or api-key
header: Header to use (defaults to authorization for most schemes, x-api-key for api-key)
username: Username for basic authentication
secret (required): Password (basic), token (bearer), or API key (api-key)

In this section: