Skip to main content

Commands

The Esper CLI follows a resource-oriented command structure with consistent patterns across all operations.

Command Structure​

All Esper CLI commands follow this pattern:

esper [global-options] <resource> <action> [options]

Global options like --output json apply to any command for programmatic integration.

Profile Management​

profile add​

Registers a new environment profile for quick context switching.

# Production environment
esper profile add prod --api-base https://api.esperr.com --tenant-id prod-tenant

# Staging environment
esper profile add staging --api-base https://staging.esperr.com --tenant-id staging-tenant

profile use​

Switches the active profile context.

esper profile use prod
tip

Profile switching persists across terminal sessions via ~/.config/esper/config.json.

profile show​

Displays current profile configuration including API endpoint and tenant.

esper profile show

Resource Operations​

The CLI provides CRUD operations for all builder resources. Each resource supports consistent verbs: list, create, update, delete.

Actions​

Actions define semantic traffic behaviors that policies evaluate.

List all actions​

esper action list
esper action list --output json  # For scripting

Create action​

# From template for quick prototyping
esper action create --template default

# From JSON definition
esper action create --file ./login-action.json

Update action​

esper action update --file ./login-action-v2.json
caution

Action updates affect all policies referencing them. Test with replay jobs first.

Delete action​

esper action delete <action-id>

Entities​

Entities establish identity semantics over encoded traffic.

List entities​

esper entity list

Create entity​

# Generate starter template
esper entity create --template default > entity.json

# Deploy from definition
esper entity create --file ./entity.json

Update entity​

esper entity update --file ./entity-updated.json

Delete entity​

esper entity delete <entity-id>

Mitigations​

Mitigations define response behaviors when policies match.

List mitigations​

esper mitigation list

Create mitigation​

# Common mitigation types have templates
esper mitigation create --template monitor
esper mitigation create --template block
esper mitigation create --template challenge

# Custom mitigation
esper mitigation create --file ./custom-mitigation.json

Update mitigation​

esper mitigation update --file ./mitigation-v2.json
info

Mitigation updates apply to new evaluations only. Active mitigations continue with their original configuration.

Delete mitigation​

esper mitigation delete <mitigation-id>

Policies​

Policies compose actions, entities, and mitigations into evaluation rules.

List policies​

esper policy list
esper policy list --status active  # Filter by status

Create policy​

# Template includes example structure
esper policy create --template default

# Deploy complete policy
esper policy create --file ./policy.json

Apply policy (idempotent)​

esper policy apply --file ./policy.json

The apply command creates or updates based on policy_id presence in the JSON:

  • With policy_id: Updates existing policy
  • Without policy_id: Creates new policy
Best Practice

Use apply in CI/CD pipelines for declarative policy management.

Update policy​

esper policy update --file ./policy-update.json

Delete policy​

esper policy delete <policy-id>

Results & Analytics​

Policy performance​

View aggregated policy performance metrics.

# All policies
esper results policies

# Specific policy with time range
esper results policy <policy-id> --from 2024-01-01 --to 2024-01-31

Export results​

Export results for external analysis.

esper results export --format csv --output results.csv
esper results export --format json | jq '.policies[] | select(.match_rate > 0.1)'

Advanced Operations​

Batch operations​

Process multiple resources efficiently.

# Deploy all policies in directory
for file in policies/*.json; do
  esper policy apply --file "$file"
done

# Bulk delete with confirmation
esper policy list --output json | \
  jq -r '.[] | select(.status == "inactive") | .id' | \
  xargs -I {} esper policy delete {} --confirm

Dry run mode​

Validate changes without applying them.

esper policy apply --file ./policy.json --dry-run

Output formats​

Control output format for automation.

# JSON for programmatic access
esper --output json policy list

# Table for human reading (default)
esper --output table policy list

# YAML for configuration management
esper --output yaml policy show <policy-id>

Error Handling​

The CLI returns standard exit codes:

  • 0: Success
  • 1: General error
  • 2: Validation error
  • 3: Authentication error
  • 4: Resource not found
# Check command success
if esper policy apply --file ./policy.json; then
  echo "Policy applied successfully"
else
  echo "Policy application failed with code $?"
fi

Environment Variables​

Override configuration via environment for CI/CD integration.

export ESPER_API_BASE=https://api.esperr.com
export ESPER_AUTH_TOKEN=jwt_token_here
export ESPER_TENANT_ID=prod-tenant

esper policy list  # Uses env vars automatically
note

Environment variables take precedence over profile configuration.

Common Workflows​

Deploy new policy set​

# 1. Validate current state
esper policy list

# 2. Apply policies declaratively
esper policy apply --file policies/rate-limiting.json
esper policy apply --file policies/authentication.json

# 3. Verify deployment
esper results policies

Rollback policy change​

# 1. Export current policy
esper policy show <policy-id> --output json > policy-backup.json

# 2. Make changes
esper policy update --file policy-new.json

# 3. If issues, restore
esper policy apply --file policy-backup.json