Skip to main content

epilot CLI

[GitHub] [npm]

One command to call any epilot API operation. No SDK setup, no boilerplate — just npx epilot.

tip

No install needed. Run any command with npx epilot.

Use cases​

  • Quick API calls — look up entities, search data, check configurations without writing code
  • Automation & scripting — pipe JSON in/out, --json mode for jq-friendly output, --no-interactive for CI pipelines
  • AI agent tool use — structured --json output and --no-interactive mode make it ideal as a tool for LLM agents and MCP servers
  • Explore & discover — interactive operation picker, --guided mode, and built-in help with sample requests/responses for every operation

Install​

npx epilot --help

Quick start​

# Authenticate (opens browser)
epilot auth login

# List available operations for an API
epilot entity

# Call an operation
epilot entity getEntity contact abc123

# Search with a request body
epilot entity searchEntities -d '{"q":"*"}'

# Transform response with JSONata
epilot entity searchEntities -d '{"q":"*"}' --jsonata 'results[0]._title'

Usage​

epilot <api> <operationId> [params...] [flags]

Run epilot <api> to list available operations. Run epilot <api> <operationId> --help for operation details including parameters, sample calls, and sample responses.

Flags​

FlagAliasDescription
--token <token>-tBearer token for authentication
--profile <name>Use a named profile (or EPILOT_PROFILE env)
--server <url>-sOverride server base URL
--jsonOutput raw JSON (no colors, no metadata)
--verbose-vVerbose output (show request + response details)
--include-iInclude response headers in output
--jsonata <expr>JSONata expression to transform response
--guidedPrompt for all parameters interactively
--no-interactiveDisable interactive prompts (for CI/scripts)
--definition <file>Override bundled OpenAPI spec with a file or URL

Parameter flags​

FlagAliasDescription
-p key=valueSet a named parameter
-d '{...}'Request body JSON
-H 'Key: Value'Custom request header

Authentication​

# Browser-based login (opens epilot portal)
epilot auth login

# Manual token
epilot auth login --token <your-token>

# Or pass token per-command
epilot entity listSchemas --token <your-token>

# Or via environment variable
EPILOT_TOKEN=<your-token> epilot entity listSchemas

# Check auth status
epilot auth status

# Logout
epilot auth logout

Token resolution order:

  1. --token flag
  2. EPILOT_TOKEN environment variable
  3. Active profile token
  4. Stored credentials (~/.config/epilot/credentials.json)
  5. Interactive prompt (if TTY)

Parameters​

# Named parameters with -p
epilot entity getEntity -p slug=contact -p id=abc123

# Positional args map to path parameters in URL template order
epilot entity getEntity contact abc123

# Query parameters
epilot entity listSchemas -p unpublished=true

Positional arguments are mapped to path parameters in the order they appear in the URL template. For example, /v1/entity/{slug}/{id} maps the first positional arg to slug and the second to id.

Request body​

# Inline JSON with -d
epilot entity createEntity -p slug=contact -d '{"first_name":"John","last_name":"Doe"}'

# Pipe from file
cat entity.json | epilot entity createEntity -p slug=contact

# Pipe from another command
echo '{"q":"*"}' | epilot entity searchEntities

When running interactively without -d and no piped input, the CLI opens your $EDITOR with a pre-filled JSON template based on the request body schema.

Response formatting​

# Pretty-printed, syntax-highlighted JSON (default in TTY)
epilot entity getEntity contact abc123

# Raw JSON for piping to jq, etc.
epilot entity getEntity contact abc123 --json

# Include response headers
epilot entity getEntity contact abc123 --include

# Verbose: show full request + response metadata
epilot entity getEntity contact abc123 --verbose

# JSONata transformation
epilot entity searchEntities -d '{"q":"*"}' --jsonata 'results[0]._title'
epilot user getMeV2 --jsonata 'email'

In interactive mode, long output is automatically paged through less. Use --no-interactive to disable paging.

Profiles​

Manage multiple environments, similar to AWS CLI profiles:

# Create profiles
epilot profile create dev --server https://entity.dev.sls.epilot.io --token <dev-token>
epilot profile create staging --server https://entity.staging.sls.epilot.io --token <staging-token>
epilot profile create prod --token <prod-token>

# Switch active profile
epilot profile use dev

# Use per-command
epilot entity listSchemas --profile staging

# Or via environment variable
EPILOT_PROFILE=dev epilot entity listSchemas

# List / show / delete
epilot profile list
epilot profile show dev
epilot profile delete dev

Profiles store server URL, auth token, org ID, and custom headers in ~/.config/epilot/profiles.json.

Interactive mode​

When running in a TTY without required arguments, the CLI prompts interactively:

  • No operation: shows a searchable operation picker (type to filter)
  • Missing required params: prompts for each one
  • Missing request body: opens $EDITOR with a JSON template
  • No auth token: prompts to paste a token

Disable with --no-interactive for CI/scripts.

Guided mode​

Use --guided to be prompted for all parameters, not just required ones. This is useful for exploring an API operation without having to look up every available parameter.

# Walk through all parameters for getEntity
epilot entity getEntity --guided

# Guided mode also opens the body editor for operations with a request body
epilot entity searchEntities --guided

Each optional parameter shows "(optional, press Enter to skip)" so you can quickly skip ones you don't need.

OpenAPI spec override​

For unreleased API features, override the bundled OpenAPI spec:

# From a local file
epilot entity getEntity -p slug=contact -p id=abc --definition ./my-spec.json

# From a URL
epilot entity getEntity --definition https://example.com/openapi.json

# Or place in .epilot/overrides/
mkdir -p .epilot/overrides
cp my-entity-spec.json .epilot/overrides/entity.json
epilot entity getEntity contact abc123  # automatically uses override

Shell completions​

Tab completion for API names, operation IDs, and flags:

# Auto-install for your current shell
epilot completion --install

# Or generate for a specific shell
epilot completion bash
epilot completion zsh
epilot completion fish

API Commands​

Per-API command reference with all operations, parameters, and sample calls. See the API Commands section in the sidebar, or browse the table below.

APICommandReference
Access Token APIepilot access-tokenreference
Address Suggestions APIepilot address-suggestionsreference
Address APIepilot addressreference
AI Agents API - OpenAPI 3.0epilot ai-agentsreference
App APIepilot appreference
Audit Logepilot audit-logsreference
Automation APIepilot automationreference
Billing APIepilot billingreference
Blueprint Manifest APIepilot blueprint-manifestreference
Consent APIepilot consentreference
Portal APIepilot customer-portalreference
Dashboard APIepilot dashboardreference
Data Management APIepilot data-managementreference
Deduplication APIepilot deduplicationreference
Design Builder API v2epilot designreference
Document APIepilot documentreference
Messaging Settings APIepilot email-settingsreference
Email template APIepilot email-templatereference
Entity Mapping APIepilot entity-mappingreference
Entity APIepilot entityreference
Environments APIepilot environmentsreference
ERP Integration APIepilot erp-integrationreference
Event Catalog APIepilot event-catalogreference
File APIepilot filereference
Iban APIepilot ibanreference
Journey APIepilot journeyreference
Kanban APIepilot kanbanreference
Message APIepilot messagereference
Metering APIepilot meteringreference
Notes APIepilot notesreference
Notification APIepilot notificationreference
Organization APIepilot organizationreference
Partner APIepilot partner-directoryreference
Permissions APIepilot permissionsreference
Pricing Tier APIepilot pricing-tierreference
Pricing APIepilot pricingreference
Purpose APIepilot purposereference
Sandbox APIepilot sandboxreference
Submission APIepilot submissionreference
Targeting APIepilot targetingreference
Template Variables APIepilot template-variablesreference
User APIepilot userreference
Validation Rules APIepilot validation-rulesreference
Webhooksepilot webhooksreference
Workflows Definitionsepilot workflow-definitionreference
Workflows Executionsepilot workflowreference