Name	Name	Last commit message	Last commit date
parent directory ..
bin	bin
definitions	definitions
docs	docs
scripts	scripts
src	src
test	test
LICENSE	LICENSE
README.md	README.md
package.json	package.json
tsconfig.json	tsconfig.json
tsup.config.ts	tsup.config.ts

@epilot/cli

Command-line interface for all epilot APIs. One command to call any operation.

Built for developers, automation scripts, and AI agents. The epilot CLI gives you direct access to the entire epilot platform from your terminal — no SDK setup, no boilerplate, just npx epilot.

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

# Run directly (no install needed)
npx epilot --help

# Or install globally
npm install -g @epilot/cli

Usage

epilot v0.1.168 — CLI for epilot APIs

USAGE
  epilot <api> <operationId> [params...] [flags]
  epilot <api>                List operations for an API
  epilot <api> <op> --help    Show operation details

FLAGS
  -t, --token <token>     Bearer token for authentication
  --profile <name>        Use a named profile (or EPILOT_PROFILE)
  -s, --server <url>      Override server base URL
  --json                  Output raw JSON (no formatting)
  -v, --verbose           Verbose output (show request details)
  --jsonata <expr>        JSONata expression to transform response
  --guided                Prompt for all parameters interactively
  --no-interactive        Disable interactive prompts

PARAMETER FLAGS
  -p key=value             Set a named parameter
  -d '{...}'               Request body JSON
  -H 'Key: Value'          Custom header
  -i, --include            Include response headers in output

COMMANDS
  auth login              Authenticate with epilot (browser)
  auth token              Store an API token directly
  auth status             Show authentication status
  auth logout             Remove stored credentials
  profile                 Manage named profiles
  completion              Generate shell completion scripts

AGENT MODE (optional)
  auth login --agent      Register this CLI as an Agent Auth agent (org switching, silent token refresh, scoped access profiles)
  org list                List your organizations and this CLI's access
  org use <id>            Switch the active organization
  org request <id>        Request access (--access <profile> --reason "…")
  org current             Show the active organization

APIs
  access-token         Access Token API
  address              Address API
  address-suggestions  Address Suggestions API
  ai-agents            AI Agents API
  app                  App API
  audit-logs           Audit Log
  automation           Automation API
  billing              Billing API
  blueprint-manifest   Blueprint Manifest API
  calendar             Calendar API
  chat                 epilot Chat API
  configuration-hub    Configuration Hub API
  consent              Consent API
  customer-portal      Portal API
  dashboard            Dashboard API
  data-governance      Data Governance API
  deduplication        Deduplication API
  design               Design Builder API v2
  document             Document API
  email-settings       Messaging Settings API
  email-template       Email template API
  entity               Entity API
  entity-mapping       Entity Mapping API
  environments         Environments API
  event-catalog        Event Catalog API
  file                 File API
  iban                 Iban API
  identity             Identity API
  integration-toolkit  Integration Toolkit API
  journey              Journey API
  kanban               Kanban API
  message              Message API
  metering             Metering API
  notes                Notes API
  notification         Notification API
  organization         Organization API
  partner-directory    Partner Directory API
  permissions          Permissions API
  pricing              Pricing API
  pricing-tier         Pricing Tier API
  purpose              Purpose API
  query                Query API
  sandbox              Sandbox API
  sharing              Sharing API
  snapshot             Snapshot API
  submission           Submission API
  targeting            Targeting API
  template-variables   Template Variables API
  user                 User API
  validation-rules     Validation Rules API
  webhooks             Webhooks
  workflow             Workflows Executions
  workflow-definition  Workflows Definitions

EXAMPLES
  $ epilot auth login
  $ epilot user getMeV2
  $ epilot entity getEntity contact abc123
  $ epilot entity searchEntities -d '{"q":"*"}'
  $ epilot entity searchEntities --jsonata 'results[0]._title'
  $ echo '{"q":"*"}' | epilot entity searchEntities
  $ epilot auth login --agent --org 739224   # agent mode (optional)
  $ epilot org request 739224 --access config:write --reason "Fix the PV journey mapping"

Run epilot <api> to list available operations.
Run epilot <api> <operationId> --help for operation details.

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:

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

Agent mode (optional)

epilot auth login --agent registers the CLI through the Agent Auth Protocol (via @epilot/agent-auth): your machine is a host, the CLI is an agent you approve once in the browser, and short-lived epilot tokens are issued per organization and refreshed silently. In return you get organization switching, scoped access profiles and sessions that outlive a single token. Plain logins are not affected: a profile without an agent behaves exactly as before.

# Register the CLI as an agent and approve it in the browser (read access, your login organization)
epilot auth login --agent

# A specific organization, an access profile and the purpose shown to the approving user
epilot auth login --agent --org 739224 --access config:write --reason "Fix the PV registration journey mapping"

# Non-interactive (CI / agents): requires --org; prints the approval URL and polls until approved
epilot auth login --agent --org 739224 --no-interactive --json

# Status shows the agent, its grants (profile, expiry, reason); logout revokes the agent
epilot auth status
epilot auth logout

Access profiles scope what the issued tokens may do. read is the default and lives as long as the agent; every other profile is an escalation that requires a --reason (10–200 characters, prompted for in a TTY) and expires. The flag is --access because --profile already selects a named CLI profile:

`--access`	Meaning	Read-only	Expires after
`read`	Read everything you can see	yes	never (agent lifetime)
`config:read`	Read configuration (journeys, automations, workflows, schemas, portals, designs)	yes	7 days
`config:write`	Change configuration	no	24 hours
`data:read`	Read business data (contacts, opportunities, orders, files, messages)	yes	7 days
`data:write`	Change business data	no	24 hours
`full`	Everything your account can do	no	24 hours

Anonymization is a read-only property: --anonymize (and org request without --full-pii) only applies to read profiles. Combining --anonymize with a write profile is an error ("anonymize is only available with read profiles"), because an agent must never write masked data back. --readonly with a write profile downgrades it to its read sibling (config:write → config:read, full → read). On the approval page the user can only narrow what the CLI asked for; the CLI then issues tokens for the profile that was actually granted.

Organizations

One approval grants access to one organization. Switching or adding organizations goes through epilot org (agent mode only — without an agent the commands exit 1 with "This profile has no agent identity. Run epilot auth login --agent first.", or {"error":"agent_required"} with --json):

epilot org list                 # organizations with access (profile, anonymized, "expires in 23h", pending)
epilot org current              # the active organization and its profile
epilot org use 911210           # switch: issues a token under the most permissive grant (asks for access otherwise)
epilot org use 911210 --access data:read            # ...or under a specific granted profile
epilot org request 911210       # ask for read, anonymized access (approved in the browser)
epilot org request 911210 --full-pii                # read access with unmasked personal data
epilot org request 911210 --access data:write --reason "Import meter readings from the portal export"
epilot org request 911210 --access full --reason "…" --no-interactive --json   # prints the approval, exits 0 (pending)

--write is a deprecated alias for --access full. Write profiles always get full personal data (--full-pii is implied). After an approval that happened outside the CLI (e.g. from a --no-interactive request), epilot org use <id> completes the switch; auth status lists every grant with its profile, expiry and reason.

Silent refresh

Issued tokens are short-lived. Whenever a command runs and the stored token of an agent-mode profile is missing or expires within two minutes, the CLI issues a fresh one through the agent (same organization and profile) and stores it — you stay logged in for as long as the agent and its grant are active. If the agent was revoked or expired, run epilot auth login --agent again. A plain epilot auth login (or --token) on the same profile revokes that profile's agent, so plain tokens are never replaced.

Local state lives in ~/.config/epilot/agent-auth/ (host.json for the machine key, agents/<profile>.json for the per-profile agent; both mode 0600). EPILOT_AGENT_AUTH_ISSUER overrides the Agent Auth server URL (defaults per stage: --use-dev, --use-staging).

Profiles

Manage multiple environments, similar to AWS CLI profiles:

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

Parameters

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

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

# Query parameters
epilot entity listSchemas -p unpublished=true

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

Response Formatting

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

# Raw JSON (for piping)
epilot entity getEntity contact abc123 --json

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

# Verbose (show request details)
epilot entity getEntity contact abc123 --verbose

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

Server Override

# Use a custom server URL
epilot entity listSchemas --server http://localhost:3000

# Or set it in a profile
epilot profile create local --server http://localhost:3000
epilot profile use local

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

Interactive Mode

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

No operation: shows a searchable operation picker
Missing required params: prompts for each one
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.

Shell Completions

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

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

# Or install for a specific shell
epilot completion --install bash
epilot completion --install zsh
epilot completion --install fish

This adds the completion script to your shell config (~/.bashrc, ~/.zshrc, or ~/.config/fish/completions/epilot.fish). Restart your shell or source the config file to activate.

You can also set up completions manually:

# Bash — add to ~/.bashrc
eval "$(epilot completion bash)"

# Zsh — add to ~/.zshrc
eval "$(epilot completion zsh)"

# Fish — save to completions dir
epilot completion fish > ~/.config/fish/completions/epilot.fish

API Reference

Full documentation with sample calls and responses for all APIs:

docs/index.md

API	Command	Docs
Access Token API	`epilot access-token`	docs
Address API	`epilot address`	docs
Address Suggestions API	`epilot address-suggestions`	docs
AI Agents API	`epilot ai-agents`	docs
App API	`epilot app`	docs
Audit Log	`epilot audit-logs`	docs
Automation API	`epilot automation`	docs
Billing API	`epilot billing`	docs
Blueprint Manifest API	`epilot blueprint-manifest`	docs
Calendar API	`epilot calendar`	docs
epilot Chat API	`epilot chat`	docs
Configuration Hub API	`epilot configuration-hub`	docs
Consent API	`epilot consent`	docs
Portal API	`epilot customer-portal`	docs
Dashboard API	`epilot dashboard`	docs
Data Governance API	`epilot data-governance`	docs
Deduplication API	`epilot deduplication`	docs
Design Builder API v2	`epilot design`	docs
Document API	`epilot document`	docs
Messaging Settings API	`epilot email-settings`	docs
Email template API	`epilot email-template`	docs
Entity API	`epilot entity`	docs
Entity Mapping API	`epilot entity-mapping`	docs
Environments API	`epilot environments`	docs
Event Catalog API	`epilot event-catalog`	docs
File API	`epilot file`	docs
Iban API	`epilot iban`	docs
Identity API	`epilot identity`	docs
Integration Toolkit API	`epilot integration-toolkit`	docs
Journey API	`epilot journey`	docs
Kanban API	`epilot kanban`	docs
Message API	`epilot message`	docs
Metering API	`epilot metering`	docs
Notes API	`epilot notes`	docs
Notification API	`epilot notification`	docs
Organization API	`epilot organization`	docs
Partner Directory API	`epilot partner-directory`	docs
Permissions API	`epilot permissions`	docs
Pricing API	`epilot pricing`	docs
Pricing Tier API	`epilot pricing-tier`	docs
Purpose API	`epilot purpose`	docs
Query API	`epilot query`	docs
Sandbox API	`epilot sandbox`	docs
Sharing API	`epilot sharing`	docs
Snapshot API	`epilot snapshot`	docs
Submission API	`epilot submission`	docs
Targeting API	`epilot targeting`	docs
Template Variables API	`epilot template-variables`	docs
User API	`epilot user`	docs
Validation Rules API	`epilot validation-rules`	docs
Webhooks	`epilot webhooks`	docs
Workflows Executions	`epilot workflow`	docs
Workflows Definitions	`epilot workflow-definition`	docs

Development

# Install dependencies
pnpm install

# Build the workspace dependency once (bundled into the CLI by tsup; also needed by tests and `pnpm dev`)
pnpm --filter @epilot/agent-auth build

# Generate API commands + definitions + docs from client specs
pnpm generate

# Run in dev mode
pnpm dev -- entity listSchemas

# Build
pnpm build

# Run tests
pnpm test

Navigation Menu

Repository navigation

cli

cli

README.md

@epilot/cli

Install

Usage

Authentication

Agent mode (optional)

Organizations

Silent refresh

Profiles

Parameters

Request Body

Response Formatting

Server Override

OpenAPI Spec Override

Interactive Mode

Guided Mode

Shell Completions

API Reference

Development

FilesExpand file tree

cli

Directory actions

More options

Directory actions

More options

Latest commit

History

cli

Folders and files

parent directory

README.md

@epilot/cli

Install

Usage

Authentication

Agent mode (optional)

Organizations

Silent refresh

Profiles

Parameters

Request Body

Response Formatting

Server Override

OpenAPI Spec Override

Interactive Mode

Guided Mode

Shell Completions

API Reference

Development