# Configuration

The Escape CLI requires minimal configuration to get started. This guide covers authentication setup and optional configuration options.

## Authentication

### Obtaining Your API Key

1. Navigate to your [Escape user profile](<https://app.escape.tech/user/profile/>)
2. Locate the **API Key** section
3. Copy your API key. The CLI expects a UUID-formatted key.

> [!WARNING]
>
> **API Key Security**
>
> Treat your API key as a sensitive credential. Never commit it to version control or share it publicly. Anyone with access to your API key can perform actions on your behalf in the Escape platform.

### Setting the API Key

The Escape CLI authenticates using the `ESCAPE_API_KEY` environment variable.

#### Interactive Shell Sessions

**Bash/Zsh (Linux/macOS):**

```bash
export ESCAPE_API_KEY="<YOUR_API_KEY>"
```

To make this persistent across sessions, add the export statement to your shell configuration file:

```bash
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
echo 'export ESCAPE_API_KEY="<YOUR_API_KEY>"' >> ~/.bashrc
source ~/.bashrc
```

**PowerShell (Windows):**

```powershell
$env:ESCAPE_API_KEY = "<YOUR_API_KEY>"
```

For persistent configuration:

```powershell
[System.Environment]::SetEnvironmentVariable('ESCAPE_API_KEY', '<YOUR_API_KEY>', 'User')
```

**Command Prompt (Windows):**

```text
set ESCAPE_API_KEY=<YOUR_API_KEY>
```

#### CI/CD Pipelines

Configure the API key as a secret environment variable in your CI/CD platform:

**GitHub Actions:**

```yaml
env:
  ESCAPE_API_KEY: ${{ secrets.ESCAPE_API_KEY }}
```

**GitLab CI:**

```yaml
variables:
  ESCAPE_API_KEY: $ESCAPE_API_KEY
```

**Jenkins:**

```groovy
environment {
    ESCAPE_API_KEY = credentials('escape-api-key')
}
```

See [CI/CD Integration](<https://docs.escape.tech/documentation/automate/ci-cd/index.md>) for complete examples.

#### Docker Containers

Pass the API key as an environment variable:

```bash
docker run -e ESCAPE_API_KEY="${ESCAPE_API_KEY}" -it --rm escapetech/cli:latest version
```

Or use an environment file:

```bash
# .env file
ESCAPE_API_KEY=<YOUR_API_KEY>
```

```bash
docker run --env-file .env -it --rm escapetech/cli:latest version
```

### Verify Authentication

Test your authentication by listing available locations:

```bash
escape-cli locations list
```

If authentication is successful, you'll see your configured locations. If it fails, verify:

1. The API key is correctly set in your environment
2. The API key is valid and not expired
3. Your network allows connections to the Escape API

## Optional Configuration

### Private Location Kubernetes Integration

`ESCAPE_K8S_INTEGRATION` applies only to `escape-cli locations start`. Kubernetes integration is enabled unless this variable is `false`.

```bash
export ESCAPE_K8S_INTEGRATION=false
```

Set it to `false` to skip Kubernetes integration when starting a Private Location.

### Environment Variable Reference

| Variable | Behavior |
| --- | --- |
| `ESCAPE_API_KEY` | UUID-formatted API key. |
| `ESCAPE_AUTHORIZATION` | Raw `Authorization` header; takes precedence over `ESCAPE_API_KEY`. |
| `ESCAPE_API_URL` | API base URL; defaults to `https://public.escape.tech`. |
| `ESCAPE_COLOR_DISABLED` | Set to `true` to disable colored output. |
| `ESCAPE_VERBOSITY` | Logging verbosity; defaults to `0`. |
| `ESCAPE_SSL_CERT_PATH` | PEM certificate file used as the root CA pool for Escape API requests. Replaces the system roots. |
| `ESCAPE_SSL_INSECURE` | Set to `true` to disable certificate verification for Escape API requests. |
| `ESCAPE_FRONTEND_PROXY_URL` | Proxy URL for requests to the Escape platform. |
| `ESCAPE_REPEATER_PROXY_URL` | Legacy proxy variable; takes precedence over `ESCAPE_FRONTEND_PROXY_URL`. |
| `ESCAPE_BACKEND_PROXY_URL` | Private Location proxy URL for connections to scan targets. |
| `ESCAPE_PRIVATE_LOCATION_URL` | Override the Private Location SSH server address. |
| `ESCAPE_K8S_INTEGRATION` | Set to `false` to skip Kubernetes integration in `locations start`. |

### Output Formatting

Control the output format per command using the `--output` or `-o` flag:

```bash
escape-cli locations list --output json
```

**Supported formats:**

- `pretty` - Human-readable output with tables (default)
- `json` - JSON format for scripting and parsing
- `yaml` - YAML format for configuration management
- `schema` - JSON Schema of the output (useful for AI agent integration)

### Logging and Debug Mode

Enable verbose logging for troubleshooting using the repeatable `--verbose` / `-v` flag:

```bash
# Debug logging
escape-cli scans list -v

# Trace logging
escape-cli scans list -vv

# HTTP / raw debug logging
escape-cli scans list -vvv
```

You can also set the verbosity level through the `ESCAPE_VERBOSITY` environment variable (an integer, default `0`):

```bash
export ESCAPE_VERBOSITY=1
```

## Configuration Best Practices

### Development Environments

Create a `.env` file in your project directory (ensure it's in `.gitignore`):

```bash
# .env
ESCAPE_API_KEY=<YOUR_API_KEY>
ESCAPE_VERBOSITY=0
```

Load it before running commands:

```bash
# Load environment variables
source .env

# Run CLI commands
escape-cli scans list
```

### Production Environments

1. **Use Secret Management**: Store API keys in a secure secret management system (AWS Secrets Manager, HashiCorp Vault)
2. **Rotate Keys Regularly**: Generate new API keys periodically and update your configuration
3. **Least Privilege**: Use API keys with the minimum required permissions for each use case
4. **Audit Access**: Monitor API key usage through the Escape platform

### Team Environments

1. **Individual API Keys**: Each team member should use their own API key for traceability
2. **Service Accounts**: Create dedicated API keys for automated systems and CI/CD pipelines
3. **Documentation**: Document which API keys are used in which environments

## Configuration Files

Configure the Escape CLI through environment variables. To keep settings in a file, load the file into your shell before running commands, as shown in [Development Environments](<#development-environments>).

## Proxy Configuration

For CLI requests to Escape, set `ESCAPE_FRONTEND_PROXY_URL`:

```bash
export ESCAPE_FRONTEND_PROXY_URL=http://proxy.example.com:8080
```

The CLI doesn't use `HTTP_PROXY`, `HTTPS_PROXY`, or `NO_PROXY` for its API client. For Private Location target connections, use `ESCAPE_BACKEND_PROXY_URL`. See [Private Location Proxy Configuration](<https://docs.escape.tech/documentation/platform/private-location/proxy/index.md>).

## Troubleshooting

### Authentication Failures

**Error: `ESCAPE_API_KEY invalid UUID format: ...`**

- Verify the API key is correctly copied from your profile
- Check for extra spaces or newlines in the environment variable
- Ensure the API key hasn't been revoked

**Error: `ESCAPE_API_KEY environment variable isn't set. Get your key here: https://app.escape.tech/user/profile/`**

- Confirm the `ESCAPE_API_KEY` environment variable is set
- Check the variable is available in the current shell session: `echo $ESCAPE_API_KEY`

### Connection Issues

**Connection Timeouts**

- Verify network connectivity to `public.escape.tech`
- Check firewall rules allow outbound HTTPS connections
- Confirm proxy settings if applicable

**Certificate Verification Failures**

- Ensure system certificates are up to date
- Check for corporate SSL inspection that may interfere with API calls

### Permission Errors

**Permission Failures**

- Verify your API key has the required permissions
- Contact your Escape organization administrator to adjust permissions

## Next Steps

With authentication configured, proceed to [Getting Started](<https://docs.escape.tech/documentation/automate/cli/getting-started/index.md>) to learn essential CLI commands and workflows.