Configuration files

The DataRobot CLI stores your authentication credentials and preferences in configuration files. This guide explains how configuration files work, where they're stored, and how to manage them.

[!NOTE] First time? If you're new to the CLI, you typically don't need to manually create configuration files. They're automatically created when you run dr auth set-url and dr auth login. See the Quick start guide for initial setup.

Configuration location

The CLI automatically stores configuration files in a standard location based on your operating system:

Platform	Location
Linux	`~/.config/datarobot/drconfig.yaml`
macOS	`~/.config/datarobot/drconfig.yaml`
Windows	`%USERPROFILE%\.config\datarobot\drconfig.yaml`

[!NOTE] The CLI also writes a state file (state.yaml) in the same directory. This file stores runtime state such as plugin update-check timestamps. You do not normally need to edit it, but you can delete it to reset all stored state (e.g. to force an immediate update check).

Configuration structure

Main configuration file (`drconfig.yaml`)

The main configuration file (drconfig.yaml) stores your DataRobot connection settings and authentication token. Here's what it looks like:

# DataRobot Connection
endpoint: DATA_ROBOT_ENDPOINT_URL # e.g. https://app.datarobot.com
token: API_KEY_HERE

Configuration fields:

endpoint: Your DataRobot instance URL (e.g., https://app.datarobot.com)
token: Your API authentication token (automatically stored after dr auth login)

[!NOTE] You typically don't need to edit this file manually. The CLI manages it automatically when you use dr auth set-url and dr auth login.

State file (`state.yaml`)

The CLI maintains a separate state file alongside drconfig.yaml:

~/.config/datarobot/state.yaml

This file tracks runtime state that persists between CLI invocations:

Key	Description
`plugin_update_checks`	Map of plugin name → timestamp of the last update check

Example state.yaml:

plugin_update_checks:
  assist: 2026-03-23T14:00:00Z

You do not need to edit this file manually. The CLI manages it automatically. Common reasons to interact with it:

# Reset the update-check cooldown for all plugins (force an immediate check next run)
rm ~/.config/datarobot/state.yaml

# Reset the cooldown for a single plugin only
# (edit the file and remove the relevant line, or use yq)
yq -i 'del(.plugin_update_checks.assist)' ~/.config/datarobot/state.yaml

The state file respects XDG_CONFIG_HOME. If that variable is set, the file is written to $XDG_CONFIG_HOME/datarobot/state.yaml rather than ~/.config/datarobot/state.yaml.

Environment-specific configs

[!TIP] If you work with multiple DataRobot environments (development, staging, production), you can maintain separate configuration files for each. For example:
# Development
~/.config/datarobot/dev-config.yaml

# Staging
~/.config/datarobot/staging-config.yaml

# Production
~/.config/datarobot/prod-config.yaml

Switch between them:

export DATAROBOT_CLI_CONFIG=~/.config/datarobot/dev-config.yaml
dr templates list

Configuration options

Connection settings

# Required: DataRobot instance URL
endpoint: https://app.datarobot.com

# Required: API authentication key
token: api key here

Environment variables

Override configuration with environment variables:

Connection

# DataRobot endpoint URL
export DATAROBOT_ENDPOINT=https://app.datarobot.com

# API token (not recommended for security)
export DATAROBOT_API_TOKEN=your_api_token

CLI behavior

# Custom config file path
export DATAROBOT_CLI_CONFIG=~/.config/datarobot/custom-config.yaml

# Editor for text editing
export EDITOR=nano

# Force setup wizard to run even if already completed
export DATAROBOT_CLI_FORCE_INTERACTIVE=true

# API consumer tracking (default: true)
# Set to false to disable the X-DataRobot-Api-Consumer-Trace header on API requests.
# Matches the Python SDK's DATAROBOT_API_CONSUMER_TRACKING_ENABLED behavior.
# When enabled, the header value identifies the command being run using dot-notation:
#   datarobot.cli.<command>.<subcommand>  (e.g. datarobot.cli.templates.setup)
export DATAROBOT_API_CONSUMER_TRACKING_ENABLED=false

Advanced flags

The CLI supports advanced command-line flags for special use cases:

# Skip authentication checks (advanced users only)
dr templates list --skip-auth

# Force setup wizard to run (ignore completion state)
dr templates setup --force-interactive

# Enable verbose logging
dr templates list --verbose

# Enable debug logging
dr templates list --debug

# Timeout for plugin discovery (0s disables discovery)
dr --plugin-discovery-timeout 2s --help

[!WARNING] The --skip-auth flag bypasses all authentication checks and should only be used when you understand the implications. Commands requiring API access will likely fail without valid credentials.

Configuration priority

When the CLI needs configuration settings, it looks for them in this order (highest to lowest priority):

Command-line flags (e.g., --config <path>)—overrides everything.
Environment variables (e.g., DATAROBOT_CLI_CONFIG)—overrides config files.
Config files (e.g., ~/.config/datarobot/drconfig.yaml)—default location.
Built-in defaults—fallback values.

This means if you set an environment variable, it will take precedence over what's in your config file. This is useful for temporarily overriding settings without editing files.

Security best practices

Protect configuration files

# Verify permissions (should be 600)
ls -la ~/.config/datarobot/drconfig.yaml

# Fix permissions if needed
chmod 600 ~/.config/datarobot/drconfig.yaml
chmod 700 ~/.config/datarobot/

Don't commit credentials

[!WARNING] Never commit configuration files containing credentials. To ensure this, add them to .gitignore:

# DataRobot credentials
.config/datarobot/
.datarobot/
drconfig.yaml
config.yaml
*.yaml
!.env.template

Use environment-specific configs

# Never use production credentials in development
# Keep separate config files
~/.config/datarobot/
├── drconfig.yaml        # Default config
├── dev-config.yaml      # Development
├── staging-config.yaml  # Staging
└── prod-config.yaml     # Production

Avoid environment variables for secrets

# ❌ Don't do this (visible in process list)
export DATAROBOT_API_TOKEN=my_secret_token

# ✅ Do this instead (use config file)
dr auth login

Advanced configuration

Custom templates directory

templates:
  default_clone_dir: ~/workspace/datarobot

Or via environment:

export DR_TEMPLATES_DIR=~/workspace/datarobot

Logging

The CLI supports two verbosity levels controlled by global flags or config keys:

Flag	Config key	Level	Use for
`--verbose`	`verbose: true`	INFO	Operational detail (e.g., HTTP request summary, progress)
`--debug`	`debug: true`	DEBUG	Full execution tracing (e.g., request/response bodies, internal state)

Set permanently in your config file:

verbose: true
debug: true

Or enable per-invocation:

dr --verbose templates list
dr --debug templates list

When debug mode is enabled, the CLI writes a .dr-tui-debug.log file in your home directory alongside stderr output. This file captures all DEBUG-level messages including third-party SDK logs (for example, [amplitude] prefixed telemetry HTTP traces).

[!WARNING] Debug output may contain sensitive data. Never share debug logs publicly without reviewing them first. The CLI redacts known sensitive config keys (tokens, passwords) from debug output, but command output and API responses may still expose project data.

Configuration examples

Development environment

~/.config/datarobot/dev-config.yaml:

endpoint: https://dev.datarobot.com
token: api token for dev

Usage:

export DATAROBOT_CLI_CONFIG=~/.config/datarobot/dev-config.yaml
dr templates list

Production environment

~/.config/datarobot/prod-config.yaml:

endpoint: https://app.datarobot.com
token: api key for prod

Usage:

export DATAROBOT_CLI_CONFIG=~/.config/datarobot/prod-config.yaml
dr run deploy

Enterprise with proxy

~/.config/datarobot/enterprise-config.yaml:

datarobot:
  endpoint: https://datarobot.enterprise.com
  token: enterprise_key
  proxy: http://proxy.enterprise.com:3128
  verify_ssl: true
  ca_cert_path: /etc/ssl/certs/enterprise-ca.pem
  timeout: 120

preferences:
  log_level: warn

Troubleshooting

Configuration not loading

Problem: The CLI cannot find or read the configuration file. Common causes:

Config file doesn't exist (first-time setup)
Incorrect file path
Permission issues
Environment variable overriding the default path
Config file in wrong location

Solution:

# Check if config file exists
ls -la ~/.config/datarobot/drconfig.yaml

# If file doesn't exist, create it by running:
dr auth set-url https://app.datarobot.com
dr auth login

# Verify it's readable
cat ~/.config/datarobot/drconfig.yaml

# Check environment variables that might override the path
env | grep DATAROBOT

# Verify the directory exists
ls -la ~/.config/datarobot/

If using a custom config path:

# Verify the environment variable is set correctly
echo $DATAROBOT_CLI_CONFIG

# Test with explicit path
dr templates list --config ~/.config/datarobot/drconfig.yaml

Invalid configuration

Problem: YAML syntax errors in the configuration file. Common causes:

Missing colons (:) after keys
Incorrect indentation (YAML is sensitive to spaces)
Invalid YAML characters
Unclosed quotes or brackets
Mixing tabs and spaces

Solution:

# The CLI will report syntax errors with line numbers
$ dr templates list
Error: Failed to parse config file: yaml: line 5: could not find expected ':'

# Fix syntax and try again
vim ~/.config/datarobot/drconfig.yaml
# or
nano ~/.config/datarobot/drconfig.yaml

Example of correct YAML format:

# Correct format
datarobot:
  endpoint: https://app.datarobot.com
  token: your-api-token-here

# Common mistakes:
# ❌ Missing colon: endpoint https://app.datarobot.com
# ❌ Wrong indentation (must use spaces, not tabs)
# ❌ Missing quotes for values with special characters

Validate YAML syntax:

# Use a YAML validator or check manually
python3 -c "import yaml, os; yaml.safe_load(open(os.path.expanduser('~/.config/datarobot/drconfig.yaml')))"

Permission denied

Problem: The CLI cannot read or write the configuration file due to file system permissions. This can occur when:

File permissions are too restrictive for the current user
Directory permissions prevent file access
File was created by a different user (e.g., with sudo)
SELinux or AppArmor restrictions (Linux)

Solution:

# Fix file permissions (owner read/write only)
chmod 600 ~/.config/datarobot/drconfig.yaml

# Fix directory permissions (owner read/write/execute)
chmod 700 ~/.config/datarobot/

# Verify permissions
ls -la ~/.config/datarobot/drconfig.yaml
# Should show: -rw------- (600)

If file was created with sudo:

# Change ownership to your user
sudo chown $USER:$USER ~/.config/datarobot/drconfig.yaml
chmod 600 ~/.config/datarobot/drconfig.yaml

For Windows:

# Check file permissions
icacls %USERPROFILE%\.config\datarobot\drconfig.yaml

# If needed, grant full control to your user
icacls %USERPROFILE%\.config\datarobot\drconfig.yaml /grant %USERNAME%:F

Multiple configs

Problem: Managing multiple environments (dev, staging, production) with separate configurations.

Solution:

# List all config files
find ~/.config/datarobot -name "*.yaml"

# Switch between them using environment variable
export DATAROBOT_CLI_CONFIG=~/.config/datarobot/dev-config.yaml
dr templates list

# Or use inline for single commands
DATAROBOT_CLI_CONFIG=~/.config/datarobot/prod-config.yaml dr templates list

Create a helper script for easy switching:

# Add to ~/.bashrc or ~/.zshrc
alias dr-dev='export DATAROBOT_CLI_CONFIG=~/.config/datarobot/dev-config.yaml'
alias dr-prod='export DATAROBOT_CLI_CONFIG=~/.config/datarobot/prod-config.yaml'
alias dr-staging='export DATAROBOT_CLI_CONFIG=~/.config/datarobot/staging-config.yaml'

# Usage:
dr-dev
dr templates list  # Uses dev config

dr-prod
dr templates list  # Uses prod config

[!TIP] Always verify which config is active before running commands in production:
 echo "Current config: $DATAROBOT_CLI_CONFIG"
 cat $DATAROBOT_CLI_CONFIG
Example output:
 Current config: ~/.config/datarobot/prod-config.yaml

State tracking

The CLI maintains state information about your interactions with repositories to provide a better user experience. State is tracked per-repository and stores metadata about command executions.

State file location

The CLI stores state locally within each repository:

.datarobot/cli/state.yaml in template directory

Tracked information

The state file tracks:

CLI version: Version of the CLI used for the last successful execution
Last start: Timestamp of the last successful dr start execution
Last dotenv setup: Timestamp of the last successful dr dotenv setup execution

State file format

cli_version: 1.0.0
last_start: 2025-11-13T00:02:07.615186Z
last_dotenv_setup: 2025-11-13T00:15:30.123456Z

All timestamps are in ISO 8601 format (UTC).

How state is used

dr start: Updates state after successful execution
dr dotenv setup: Records when environment setup was completed
dr templates setup: Skips dotenv setup if it was already completed (based on state)

Managing state

State files are automatically created and updated. To reset state for a repository:

# Remove repository state
rm .datarobot/cli/state.yaml

You can also force the wizard to run without deleting the state file by using the --force-interactive flag:

# Force re-execution of setup wizard while preserving state
dr templates setup --force-interactive

# Or via environment variable
export DATAROBOT_CLI_FORCE_INTERACTIVE=true
dr templates setup

This flag makes commands behave as if setup has never been completed, while still updating the state file. This is useful for:

Testing setup flows
Forcing reconfiguration without losing state history
Development and debugging

State files are small and do not require manual management under normal circumstances. Each repository maintains its own state independently.

Configuration files

Configuration location

Configuration structure

Main configuration file (drconfig.yaml)

State file (state.yaml)

Environment-specific configs

Configuration options

Connection settings

Environment variables

Connection

CLI behavior

Advanced flags

Configuration priority

Security best practices

Protect configuration files

Don't commit credentials

Use environment-specific configs

Avoid environment variables for secrets

Advanced configuration

Custom templates directory

Logging

Configuration examples

Development environment

Production environment

Enterprise with proxy

Troubleshooting

Configuration not loading

Invalid configuration

Permission denied

Multiple configs

State tracking

State file location

Tracked information

State file format

How state is used

Managing state

See also

Main configuration file (`drconfig.yaml`)

State file (`state.yaml`)