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
2. Locate the API Key section
3. Copy your API key. The CLI expects a UUID-formatted key.

Setting the API Key¶

The Escape CLI authenticates using the ESCAPE_API_KEY environment variable.

Interactive Shell Sessions¶

Bash/Zsh (Linux/macOS):

export ESCAPE_API_KEY="<YOUR_API_KEY>"

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

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

PowerShell (Windows):

$env:ESCAPE_API_KEY = "<YOUR_API_KEY>"

For persistent configuration:

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

Command Prompt (Windows):

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:

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

GitLab CI:

variables:
  ESCAPE_API_KEY: $ESCAPE_API_KEY

Jenkins:

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

See CI/CD Integration for complete examples.

Docker Containers¶

Pass the API key as an environment variable:

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

Or use an environment file:

# .env file
ESCAPE_API_KEY=<YOUR_API_KEY>

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

Verify Authentication¶

Test your authentication by listing available locations:

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.

export ESCAPE_K8S_INTEGRATION=false

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

Environment Variable Reference¶

Output Formatting¶

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

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:

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

export ESCAPE_VERBOSITY=1

Configuration Best Practices¶

Development Environments¶

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

# .env
ESCAPE_API_KEY=<YOUR_API_KEY>
ESCAPE_VERBOSITY=0

Load it before running commands:

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

Proxy Configuration¶

For CLI requests to Escape, set ESCAPE_FRONTEND_PROXY_URL:

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.

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 to learn essential CLI commands and workflows.