# Configuration files
URL: https://docs.datarobot.com/en/docs/agentic-ai/cli/configuration.html

# Configuration files

Understanding DataRobot CLI configuration files and settings.

## Configuration location

The CLI stores configuration in a platform-specific location:

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

## Configuration structure

### Main configuration file

`~/.config/datarobot/drconfig.yaml`:

```
# DataRobot Connection
endpoint: https://app.datarobot.com
token: api key here
```

### Environment-specific configs

You can maintain multiple configurations:

```
# 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
```

### Environment variables reference

| Variable | Purpose | Scope |
| --- | --- | --- |
| DATAROBOT_ENDPOINT | DataRobot instance URL (API endpoint) | Connection; overrides config |
| DATAROBOT_API_TOKEN | API token (not recommended; prefer dr auth login) | Connection; overrides config |
| DATAROBOT_CLI_CONFIG | Path to config file | CLI behavior |
| DATAROBOT_CLI_FORCE_INTERACTIVE | Force setup wizard to run (e.g., true) | CLI behavior; setup/dotenv |
| DATAROBOT_CLI_SKIP_AUTH | Skip authentication checks (e.g., true); advanced use | CLI behavior |
| DATAROBOT_VERIFY_SSL | Disable SSL verification if false; not recommended for production | Auth / connection |
| DR_TEMPLATES_DIR | Default directory for cloning templates; see Custom templates directory | Templates |
| EDITOR | Editor used for text editing (e.g., vim, nano) | dotenv edit |

### 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
```

> ⚠️ Warning:The--skip-authflag bypasses all authentication checks and should only be used when you understand the implications. Commands requiring API access will likely fail without valid credentials.

For the full list of global flags (including `--verbose`, `--debug`, and `--force-interactive`), see [Command reference - Global flags](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/index.html#global-flags).

## Configuration priority

Settings are loaded in order of precedence:

1. flags (command-line arguments, i.e. --config <path> )
2. environment variables (i.e. DATAROBOT_CLI_CONFIG=... )
3. config files (i.e. ~/.config/datarobot/drconfig.yaml )
4. defaults (built-in defaults)

## Security best practices

### 1. 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/
```

### 2. Don't commit credentials

Add to `.gitignore`:

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

### 3. Use environment-specific configs

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

### 4. 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
```

### Debugging configuration

Enable debug logging:

```
debug: true
```

Or temporarily:

```
dr --debug templates list
```

## 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

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

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

# Check environment variables
env | grep DATAROBOT
```

### Invalid configuration

```
# The CLI will report syntax errors
$ 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
```

### Permission denied

```
# Fix file permissions
chmod 600 ~/.config/datarobot/drconfig.yaml

# Fix directory permissions
chmod 700 ~/.config/datarobot/
```

### Multiple configs

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

# Switch between them
export DATAROBOT_CLI_CONFIG=~/.config/datarobot/dev-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.

### What counts as a template directory

A directory is treated as a DataRobot template directory when it contains a `.env` file (or, for some commands, a `.datarobot/` directory). This affects:

- dr run — Requires a .env file in the current directory to discover and run tasks.
- dr start — If not in a template directory, launches the template setup wizard instead of running a quickstart.
- dr task compose / dr task list — Expect a template directory (e.g., with .env and component Taskfiles).
- State tracking — State is stored per template directory in .datarobot/cli/state.yaml within that directory.

Cloned templates created by `dr templates setup` or `dr templates clone` include `.datarobot/` and, after configuration, a `.env` file, so they are recognized automatically.

### State file location

The CLI stores state locally within each template directory:

- .datarobot/cli/state.yaml in the template directory (current working 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: "0.2.38"
last_start: 2026-01-15T00:02:07.615186Z
last_dotenv_setup: 2026-01-15T00: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 template directory:

```
# Remove template 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.

## See also

- Getting started —initial setup.
- Authentication —managing credentials.

---
