> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basecut.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete reference for Basecut CLI configuration

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.

```bash theme={null}
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).

```bash theme={null}
export BASECUT_NO_BROWSER=1
```

***

### BASECUT\_NO\_UPDATE\_NOTIFIER

**Type:** String (set to any value)

Disable the CLI update notification check in interactive terminals.

```bash theme={null}
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.

```bash theme={null}
export BASECUT_DATABASE_URL="postgresql://localhost:5432/myapp_dev"
```

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
```

#### AWS\_SECRET\_ACCESS\_KEY

AWS secret key for S3 bucket access.

```bash theme={null}
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```

#### AWS\_SESSION\_TOKEN

AWS session token for temporary credentials (optional).

```bash theme={null}
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).

```bash theme={null}
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.

```bash theme={null}
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:**

```bash theme={null}
# 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](/advanced/agent-deployment#database-credentials)
* 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli-reference/snapshot-create">
    Command-line flag documentation
  </Card>

  <Card title="CI/CD Integration" icon="webhook" href="/workflows/ci-cd">
    Using environment variables in pipelines
  </Card>

  <Card title="Agent Deployment" icon="server" href="/advanced/agent-deployment">
    Environment variables for production agents
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Debug configuration issues
  </Card>
</CardGroup>