Skip to main content
The Basecut CLI reads configuration from environment variables. This is useful for CI/CD pipelines, containerized environments, and avoiding command-line repetition.

​
Core Variables

​
BASECUT_API_KEY

Type: String (required for snapshot create and self-hosted agent) Format: bc_live_* or bc_test_* Your Basecut API key for authentication with Basecut services. 
export BASECUT_API_KEY=bc_live_abc123_yoursecret
Where to get it:
  • User keys: basecut login then view in dashboard
  • Org keys: Dashboard → Organization Settings → API Keys

​
BASECUT_NO_BROWSER

Type: String (set to any value) Disable automatic browser opening during basecut login (useful for SSH or headless environments). 
export BASECUT_NO_BROWSER=1

​
BASECUT_NO_UPDATE_NOTIFIER

Type: String (set to any value) Disable the CLI update notification check in interactive terminals. 
export BASECUT_NO_UPDATE_NOTIFIER=1

​
BASECUT_DATABASE_URL

Type: String (PostgreSQL connection) Format: postgresql://user:password@host:port/database Default database connection string. Used when --source or --target flags are omitted. 
export BASECUT_DATABASE_URL="postgresql://localhost:5432/myapp_dev"
Examples: 
# Local development
export BASECUT_DATABASE_URL="postgresql://localhost:5432/myapp"

# Production (read-only user)
export BASECUT_DATABASE_URL="postgresql://readonly:pass@prod-db:5432/myapp"

# With SSL
export BASECUT_DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"

# With connection pooling
export BASECUT_DATABASE_URL="postgresql://user:pass@host:5432/db?pool_max_conns=10"

​
Cloud Storage Variables

​
AWS S3

​
AWS_ACCESS_KEY_ID

AWS access key for S3 bucket access. 
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

​
AWS_SECRET_ACCESS_KEY

AWS secret key for S3 bucket access. 
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

​
AWS_SESSION_TOKEN

AWS session token for temporary credentials (optional). 
export AWS_SESSION_TOKEN=FwoGZXIvYXdzEBYaDH...

​
AWS_REGION

Default AWS region for S3 buckets. Used as a fallback when output.region is not set in basecut.yml (including self-hosted agent --async runs). 
export AWS_REGION=us-east-1
Alternative: Use AWS CLI profiles (~/.aws/credentials)

​
Google Cloud Storage

​
GOOGLE_APPLICATION_CREDENTIALS

Path to GCS service account JSON key file. 
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
Alternative: Use gcloud auth application-default login

​
Agent Configuration

Agent settings are configured via CLI flags (not environment variables):
  • --agent-id (optional)
  • --poll-interval (default: 5s)
  • --heartbeat-interval (default: 1m)
  • --run-once (useful for testing)

​
Configuration Precedence

When a value can come from multiple sources, precedence is:
  1. CLI flags (highest priority)
  2. Environment variables
  3. Config file (basecut.yml)
  4. Defaults (lowest priority)
Example: 
# Environment variable
export BASECUT_DATABASE_URL="postgresql://localhost:5432/dev"

# This uses the env var
basecut snapshot create --config basecut.yml

# This overrides the env var
basecut snapshot create --config basecut.yml --source "postgresql://prod-db:5432/myapp"

​
Security Best Practices

  • Never commit credentials (.env, API keys) to source control
  • Use a read-only database user for extraction — see Agent Deployment
  • Use your CI platform’s secret management for BASECUT_API_KEY and cloud storage credentials
  • Use IAM roles or Workload Identity instead of static credentials when possible

​
Troubleshooting

​
”BASECUT_API_KEY not set”

Error: BASECUT_API_KEY environment variable not set
Solution: 
# Login to get your key
basecut login

# Or set manually
export BASECUT_API_KEY=bc_live_abc123_secret

​
“BASECUT_DATABASE_URL not set”

Error: database connection string required
Solution: 
# Set environment variable
export BASECUT_DATABASE_URL="postgresql://localhost:5432/myapp"

# Or use --source flag
basecut snapshot create --source "postgresql://..." --config basecut.yml

​
“Invalid AWS credentials”

Error: AccessDenied: Access Denied
Solution: 
# Verify AWS CLI works
aws s3 ls s3://your-bucket

# Check credentials are set
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY

# Or use AWS CLI credentials
aws configure

​
Next Steps

CLI Reference

Command-line flag documentation

CI/CD Integration

Using environment variables in pipelines

Agent Deployment

Environment variables for production agents

Troubleshooting

Debug configuration issues