# epilot CLI

The epilot CLI calls any epilot API operation with one command, no SDK setup or boilerplate needed: just run npx epilot.

[[GitHub](https://github.com/epilot-dev/sdk-js/tree/main/packages/cli)] [[npm](https://www.npmjs.com/package/@epilot/cli)]

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

  

```bash
npx epilot --help
```

  
  

```bash
npm install -g @epilot/cli
```

  

## Quick start

```bash
# 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

| Flag | Alias | Description |
| ---- | ----- | ----------- |
| `--token <token>` | `-t` | Bearer token for authentication |
| `--profile <name>` | | Use a named profile (or `EPILOT_PROFILE` env) |
| `--server <url>` | `-s` | Override server base URL |
| `--json` | | Output raw JSON (no colors, no metadata) |
| `--verbose` | `-v` | Verbose output (show request + response details) |
| `--include` | `-i` | Include response headers in output |
| `--jsonata <expr>` | | JSONata expression to transform response |
| `--guided` | | Prompt for all parameters interactively |
| `--no-interactive` | | Disable interactive prompts (for CI/scripts) |
| `--definition <file>` | | Override bundled OpenAPI spec with a file or URL |

### Parameter flags

| Flag | Alias | Description |
| ---- | ----- | ----------- |
| `-p key=value` | | Set a named parameter |
| `-d '{...}'` | | Request body JSON |
| `-H 'Key: Value'` | | Custom request header |

## Authentication

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

# Browser-based login restricted to a read-only session
epilot auth login --readonly

# Browser-based login with PII-anonymized entity data
epilot auth login --readonly --anonymize

# 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 (shows whether the token is read-only)
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)

### Read-only sessions

Pass `--readonly` to `epilot auth login` to obtain a read-only token. A read-only session can perform read actions (view, export, download) but is denied any write action, regardless of the roles your account holds.

```bash
epilot auth login --readonly
```

When you run this, the browser authorize page pre-checks and locks the **Read-only mode** option, so the resulting CLI session is always read-only. You can also opt into read-only mode manually from that page during a normal `epilot auth login` (the checkbox is left unchecked by default).

`epilot auth status` reports the current token's access level on the `Access` line:

```
Access:  read-only
```

vs. a normal read-write token:

```
Access:  read-write
```

### Anonymized sessions

Pass `--anonymize` to `epilot auth login` to obtain an [anonymized token](/docs/auth/access-tokens#anonymized-tokens). Personal data in entity responses, such as names, emails, phone numbers, and addresses, is replaced with pseudonyms, and entity exports are blocked. Use it when the output of the CLI goes to an AI assistant or into logs.

```bash
epilot auth login --readonly --anonymize
```

As with `--readonly`, the browser authorize page pre-checks and locks the **Anonymize mode** option. You can also check it manually during a normal `epilot auth login`. `epilot auth status` shows `Data: anonymized` for such a session.

> **Caution: Anonymization is best effort**
Custom attributes are only masked when they are recognized as personal data or marked **Anonymize** in the entity schema, and APIs other than the Entity API and Audit Log API return their data unchanged. See [PII Anonymization](/docs/auth/anonymization) for what is covered. Combine `--anonymize` with `--readonly`, so that pseudonyms can't be written back over real data.

## Parameters

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# Create profiles
epilot profile create sandbox --token <sandbox-token>
epilot profile create prod --token <prod-token>

# Switch active profile
epilot profile use sandbox

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

# Or via environment variable
EPILOT_PROFILE=sandbox epilot entity listSchemas

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

Profiles store auth token, server URL, 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.

```bash
# 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:

```bash
# 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:

```bash
# 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](commands/entity.md) section in the sidebar, or browse the table below.

| API | Command | Reference |
| --- | ------- | --------- |
| Access Token API | `epilot access-token` | [reference](commands/access-token.md) |
| Address Suggestions API | `epilot address-suggestions` | [reference](commands/address-suggestions.md) |
| Address API | `epilot address` | [reference](commands/address.md) |
| AI Agents API - OpenAPI 3.0 | `epilot ai-agents` | [reference](commands/ai-agents.md) |
| App API | `epilot app` | [reference](commands/app.md) |
| Audit Log | `epilot audit-logs` | [reference](commands/audit-logs.md) |
| Automation API | `epilot automation` | [reference](commands/automation.md) |
| Billing API | `epilot billing` | [reference](commands/billing.md) |
| Blueprint Manifest API | `epilot blueprint-manifest` | [reference](commands/blueprint-manifest.md) |
| Consent API | `epilot consent` | [reference](commands/consent.md) |
| Portal API | `epilot customer-portal` | [reference](commands/customer-portal.md) |
| Dashboard API | `epilot dashboard` | [reference](commands/dashboard.md) |
| Data Governance API | `epilot data-governance` | [reference](commands/data-governance.md) |
| Deduplication API | `epilot deduplication` | [reference](commands/deduplication.md) |
| Design Builder API v2 | `epilot design` | [reference](commands/design.md) |
| Document API | `epilot document` | [reference](commands/document.md) |
| Messaging Settings API | `epilot email-settings` | [reference](commands/email-settings.md) |
| Email template API | `epilot email-template` | [reference](commands/email-template.md) |
| Entity Mapping API | `epilot entity-mapping` | [reference](commands/entity-mapping.md) |
| Entity API | `epilot entity` | [reference](commands/entity.md) |
| Environments API | `epilot environments` | [reference](commands/environments.md) |
| ERP Integration API | `epilot erp-integration` | [reference](commands/erp-integration.md) |
| Event Catalog API | `epilot event-catalog` | [reference](commands/event-catalog.md) |
| File API | `epilot file` | [reference](commands/file.md) |
| Iban API | `epilot iban` | [reference](commands/iban.md) |
| Journey API | `epilot journey` | [reference](commands/journey.md) |
| Kanban API | `epilot kanban` | [reference](commands/kanban.md) |
| Message API | `epilot message` | [reference](commands/message.md) |
| Metering API | `epilot metering` | [reference](commands/metering.md) |
| Notes API | `epilot notes` | [reference](commands/notes.md) |
| Notification API | `epilot notification` | [reference](commands/notification.md) |
| Organization API | `epilot organization` | [reference](commands/organization.md) |
| Partner API | `epilot partner-directory` | [reference](commands/partner-directory.md) |
| Permissions API | `epilot permissions` | [reference](commands/permissions.md) |
| Pricing Tier API | `epilot pricing-tier` | [reference](commands/pricing-tier.md) |
| Pricing API | `epilot pricing` | [reference](commands/pricing.md) |
| Purpose API | `epilot purpose` | [reference](commands/purpose.md) |
| Sandbox API | `epilot sandbox` | [reference](commands/sandbox.md) |
| Submission API | `epilot submission` | [reference](commands/submission.md) |
| Targeting API | `epilot targeting` | [reference](commands/targeting.md) |
| Template Variables API | `epilot template-variables` | [reference](commands/template-variables.md) |
| User API | `epilot user` | [reference](commands/user.md) |
| Validation Rules API | `epilot validation-rules` | [reference](commands/validation-rules.md) |
| Webhooks | `epilot webhooks` | [reference](commands/webhooks.md) |
| Workflows Definitions | `epilot workflow-definition` | [reference](commands/workflow-definition.md) |
| Workflows Executions | `epilot workflow` | [reference](commands/workflow.md) |