Getting Started¶

This guide introduces you to the essential commands and workflows of the Escape CLI. After completing this guide, you'll be comfortable navigating the CLI and performing common security testing tasks.

Prerequisites¶

Before starting, ensure you have:

Command Structure¶

All Escape CLI commands follow a consistent structure:

escape-cli <resource> <action> [arguments] [flags]

Components:

<resource> - The entity you're interacting with (profiles, scans, assets, etc.)
<action> - The operation to perform (list, get, create, start, etc.)
[arguments] - Required values like IDs or file paths
[flags] - Optional parameters to modify behavior

Example:

escape-cli scans start 00000000-0000-0000-0000-000000000000 --output json

Global Flags¶

These flags work with all commands:

Flag	Short	Description	Values
`--verbose`	`-v`	Verbose output	`-v` (info), `-vv` (debug), `-vvv` (trace), `-vvvv` (http debug)
`--output`	`-o`	Output format	`pretty` (default), `json`, `yaml`

Examples:

# Enable debug logging
escape-cli scans start <profile-id> -vv

# Get JSON output
escape-cli profiles list -o json

# Trace level logging with YAML output
escape-cli assets list -vvv -o yaml

Getting Help¶

View All Commands¶

Display the complete command reference:

escape-cli help

For a comprehensive list with all subcommands:

escape-cli help-all

Command-Specific Help¶

Get detailed help for any command:

escape-cli help <resource> <action>

Examples:

escape-cli help scans start
escape-cli help profiles list
escape-cli help assets create

Essential Commands¶

Check CLI Version¶

Verify your CLI installation and version:

escape-cli version

Output:

Escape CLI version 1.2.3

List Resources¶

View your configured resources:

# List all security testing profiles
escape-cli profiles list

# List all assets in your inventory
escape-cli assets list

# List configured locations
escape-cli locations list

# List recent scans (with filtering)
escape-cli scans list -p <profile-id>

# List security issues
escape-cli issues list

# List audit logs
escape-cli audit list

# List scan events
escape-cli events list

View Resource Details¶

Get detailed information about a specific resource:

# Get profile details
escape-cli profiles get <profile-id>

# Get asset details
escape-cli assets get <asset-id>

# Get scan details
escape-cli scans get <scan-id>

Output Formats¶

The CLI supports multiple output formats to suit different use cases.

Table Format (Default)¶

Human-readable table output, ideal for interactive use:

escape-cli profiles list

Output:

ID                                    CREATED AT                ASSET TYPE  INITIATORS      NAME
00000000-0000-0000-0000-000000000000  2025-08-14T11:54:56.653Z  WEBAPP      [SCHEDULED]     My Application

JSON Format¶

Machine-readable JSON output for scripting and automation:

escape-cli profiles list --output json

Or use the short form:

escape-cli profiles list -o json

Output:

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "My Application",
    "assetType": "WEBAPP",
    "createdAt": "2025-08-14T11:54:56.653Z",
    "initiators": ["SCHEDULED"]
  }
]

Saving Output¶

Redirect output to a file using standard shell redirection:

escape-cli profiles list -o json > profiles.json

Use tee to display and save simultaneously:

escape-cli scans start <profile-id> -o json | tee scan.json

Common Workflows¶

Running a Security Scan¶

Start a scan and monitor its progress:

# Get your profile ID
escape-cli profiles list

# Start a scan (replace with your profile ID)
PROFILE_ID="00000000-0000-0000-0000-000000000000"
escape-cli scans start "${PROFILE_ID}"

# Watch the scan in real-time
escape-cli scans watch <scan-id>

# View results when complete
escape-cli scans issues <scan-id>

Searching and Filtering¶

Many commands support filtering to narrow results:

# Search profiles by name
escape-cli profiles list --search "Production"

# Filter assets by type
escape-cli assets list --types REST_FASTAPI,REST_DJANGO

# Filter by multiple criteria
escape-cli profiles list --kind BLST_REST --risk SENSITIVE_DATA

Command Aliases¶

Common commands have shorter aliases for faster typing:

Command	Aliases
`scans`	`sc`, `scan`
`profiles`	`profile`
`assets`	`asset`
`issues`	`issue`
`locations`	`loc`, `location`
`audit`	`audits`, `logs`
`events`	`event`
`custom-rules`	`cr`, `custom-rule`, `rules`
`tags`	`tag`

Subcommand aliases:

# List commands
escape-cli profiles list
escape-cli profiles ls        # Alias

# Get commands
escape-cli assets get <id>
escape-cli assets g <id>      # Alias

# Scans aliases
escape-cli scans issues <scan-id>
escape-cli scans results <scan-id>  # Alias
escape-cli scans res <scan-id>      # Alias

# Delete commands
escape-cli profiles delete <id>
escape-cli profiles del <id>  # Alias
escape-cli profiles rm <id>   # Alias

Working with JSON Output¶

Extract specific values using jq:

# Get the ID of the first profile
escape-cli profiles list -o json | jq -r '.[0].id'

# Extract all profile names
escape-cli profiles list -o json | jq -r '.[].name'

# Count total scans
escape-cli scans list <profile-id> -o json | jq 'length'

Understanding Resource Relationships¶

Escape resources are organized hierarchically:

Assets (API endpoints, web applications)
  └── Profiles (security testing configurations)
        └── Scans (individual test executions)
              └── Issues (security findings)

Typical workflow:

Create or identify an asset - The application you want to test
Create a profile - Configuration for how to test the asset
Start scans - Execute security tests against the profile
Review issues - Analyze security findings from scans

Quick Reference¶

Most Common Commands¶

# View available commands
escape-cli help

# Check version
escape-cli version

# List profiles
escape-cli profiles list

# Start a scan
escape-cli scans start <profile-id>

# Watch scan progress
escape-cli scans watch <scan-id>

# View scan results
escape-cli scans issues <scan-id>

# Get JSON output
escape-cli <command> --output json

Exit Codes¶

The CLI uses standard exit codes for automation:

0 - Success
1 - General error
2 - Invalid usage or arguments

Check the exit code in your scripts:

if escape-cli scans start "${PROFILE_ID}"; then
    echo "Scan started successfully"
else
    echo "Failed to start scan"
    exit 1
fi

Tips for Effective Use¶

Tab Completion¶

If your shell supports it, enable tab completion for faster command entry. Check the CLI documentation for shell-specific completion scripts.

Use Variables¶

Store frequently used IDs in variables:

PROFILE_ID="00000000-0000-0000-0000-000000000000"
escape-cli scans start "${PROFILE_ID}"

Combine with Shell Tools¶

Leverage standard Unix tools for powerful workflows:

# Count assets
escape-cli assets list -o json | jq 'length'

# Filter and format
escape-cli profiles list -o json | jq '.[] | select(.assetType=="REST") | .name'

# Export to CSV
escape-cli scans issues <scan-id> -o json | jq -r '.[] | [.severity, .name] | @csv'

Create Shell Aliases¶

Add shortcuts to your shell configuration:

# Add to ~/.bashrc or ~/.zshrc
alias esc="escape-cli"
alias esc-profiles="escape-cli profiles list"
alias esc-scans="escape-cli scans list"

Next Steps¶

Now that you're familiar with the basics, explore specific functionality:

Profiles Management - Create and configure security testing profiles
Assets Management - Manage your application inventory
Scans Management - Run and monitor security scans
Practical Recipes - Complete examples for common tasks
CI/CD Integration - Integrate security testing into your pipeline