Environment Variables

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:

CLI flags (highest priority)
Environment variables
Config file (basecut.yml)
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

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Environment Variables

Core Variables

BASECUT_API_KEY

BASECUT_NO_BROWSER

BASECUT_NO_UPDATE_NOTIFIER

BASECUT_DATABASE_URL

Cloud Storage Variables

AWS S3

AWS_ACCESS_KEY_ID

AWS_SECRET_ACCESS_KEY

AWS_SESSION_TOKEN

AWS_REGION

Google Cloud Storage

GOOGLE_APPLICATION_CREDENTIALS

Agent Configuration

Configuration Precedence

Security Best Practices

Troubleshooting

”BASECUT_API_KEY not set”

“BASECUT_DATABASE_URL not set”

“Invalid AWS credentials”

Next Steps

CLI Reference

CI/CD Integration

Agent Deployment

Troubleshooting

​Core Variables

​BASECUT_API_KEY

​BASECUT_NO_BROWSER

​BASECUT_NO_UPDATE_NOTIFIER

​BASECUT_DATABASE_URL

​Cloud Storage Variables

​AWS S3

​AWS_ACCESS_KEY_ID

​AWS_SECRET_ACCESS_KEY

​AWS_SESSION_TOKEN

​AWS_REGION

​Google Cloud Storage

​GOOGLE_APPLICATION_CREDENTIALS

​Agent Configuration

​Configuration Precedence

​Security Best Practices

​Troubleshooting

​”BASECUT_API_KEY not set”

​“BASECUT_DATABASE_URL not set”

​“Invalid AWS credentials”

​Next Steps

CLI Reference

CI/CD Integration

Agent Deployment

Troubleshooting

Core Variables

BASECUT_API_KEY

BASECUT_NO_BROWSER

BASECUT_NO_UPDATE_NOTIFIER

BASECUT_DATABASE_URL

Cloud Storage Variables

AWS S3

AWS_ACCESS_KEY_ID

AWS_SECRET_ACCESS_KEY

AWS_SESSION_TOKEN

AWS_REGION

Google Cloud Storage

GOOGLE_APPLICATION_CREDENTIALS

Agent Configuration

Configuration Precedence

Security Best Practices

Troubleshooting

”BASECUT_API_KEY not set”

“BASECUT_DATABASE_URL not set”

“Invalid AWS credentials”

Next Steps