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_HOMEor$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_diridentified 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-dircommand-line parameter -
The
DRIFT_HOME_DIRenvironment 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, orapi-key -
header: Header to use (defaults toauthorizationfor most schemes,x-api-keyforapi-key) -
username: Username for basic authentication -
secret(required): Password (basic), token (bearer), or API key (api-key)