CLI Reference

Complete reference for the agentowl command-line interface — authentication, tenants, endpoints, bindings, routes, policies, events, and operations.

Complete reference for the agentowl command-line interface.

Global options

Option	Description	Default
`--output <format>`	Output format: `json`, `yaml`, `table`	`table`
`--json`	Shorthand for `--output json`
`--version`	Show CLI version
`--help`	Show help

Installation

The CLI is published from this repository's packages/cli workspace as the agentowl binary. Until it is published to npm, install it from source; see Self-hosting.

Authentication

Configure API authentication. Saves credentials to ~/.agentowl/config.json (mode 0600).

agentowl login [--url <api-url>]
agentowl login --token <bearer-token> [--url <api-url>]

Option	Description	Default
`--token <token>`	API key or access token (skips the browser/device flow)
`--url <url>`	API base URL	`https://api.agentowl.dev`

Without --token, the CLI starts the browser/device-code login flow and stores the resulting oat_ access token locally.

# Hosted: use an API key from Settings → API Keys in the dashboard
agentowl login --token aok_... --url https://api.agentowl.dev

Both login modes resolve the API URL in this order: --url, AGENTOWL_API_URL, the saved URL, then https://api.agentowl.dev. Token login saves the resolved URL. Subsequent commands use the environment override, saved URL, or hosted default. For a local server, pass --url http://localhost:8787. Commands that require a tenant take its slug or ID explicitly.

Environment variable overrides (take precedence over config file):

Variable	Description
`AGENTOWL_API_TOKEN`	Bearer token
`AGENTOWL_API_URL`	API base URL
`AGENTOWL_TELEMETRY`	Set to `true` to send anonymous CLI telemetry
`AGENTOWL_TELEMETRY_URL`	Telemetry collector URL
`AGENTOWL_TELEMETRY_TOKEN`	Telemetry collector token

`agentowl logout`

Remove saved credentials (~/.agentowl/config.json).

agentowl logout

`agentowl whoami`

Show the signed-in account and plan.

agentowl whoami

`agentowl version`

Show CLI and server version.

agentowl version

`agentowl compat check`

Check CLI/server compatibility.

agentowl compat check

Tenants

Required role: any authenticated operator for create/list/inspect/delete within scope.

`agentowl tenant create <slug>`

Create a new tenant.

agentowl tenant create acme --display-name "Acme Corp"
agentowl tenant create acme --display-name "Acme Corp" --dry-run

Option	Description	Default
`--display-name <name>`	Human-readable name	Same as slug
`--dry-run`	Preview without creating

Slug must be lowercase alphanumeric with hyphens/underscores, starting with a letter or number.

`agentowl tenant list`

List tenants visible to the authenticated operator.

agentowl tenant list
agentowl tenant list --json

Platform admins see all tenants. Tenant admins see only tenants in their scope.

`agentowl tenant inspect <tenant>`

Inspect a tenant by slug or ID.

agentowl tenant inspect acme
agentowl tenant inspect t_abc123

`agentowl tenant delete <tenant>`

Delete a tenant. Requires --plan (preview) or --confirm (execute).

agentowl tenant delete acme --plan      # Preview: shows resource counts
agentowl tenant delete acme --confirm   # Execute: marks tenant as deleting

The plan shows how many bindings, endpoints, and routes will be removed.

Endpoints

Required role: platform-admin or tenant-admin (within scope).

`agentowl endpoint create [type] [name] [url_or_queue]`

Create an endpoint. Type and name can be given positionally or via --type / --name.

agentowl endpoint create webhook my-hook https://app.example.com/hook --tenant acme
agentowl endpoint create agent-runtime my-agent https://agent.example.com --tenant acme
agentowl endpoint create sip support-phone --tenant acme \
  --config '{"sip_uri":"sips:agent@voice.example.com:5061"}'
agentowl endpoint create queue my-queue https://queue.example.com/events --tenant acme \
  --config '{"queue_adapter":"http"}' --auth-type bearer --secret-ref acme/queue-token
agentowl endpoint create --type voice-runtime --name vbox \
  --runtime-url wss://voice.example.com \
  --stream-token-secret-ref acme/vbox-stream-token \
  --route-ref support@v1 --tenant acme

Option	Description	Required
`--tenant <tenant>`	Tenant slug or ID	Yes
`--type <type>`	Endpoint type (alternative to the positional)	No
`--name <name>`	Endpoint name (alternative to the positional)	No
`--config <json>`	Additional endpoint configuration object	For SIP/queue/forwarding
`--auth-type <type>`	`none`, `bearer`, or `hmac` (default `none`)	No
`--secret-ref <ref>`	Stored credential reference	For bearer/HMAC
`--runtime-url <url>`	`voice-runtime`: runtime base URL (`wss://` or `https://`)	For `voice-runtime`
`--stream-token-secret-ref <ref>`	`voice-runtime`: secret reference for the stream token (never the token)	For `voice-runtime`
`--stream-path <path>`	`voice-runtime`: stream path template, default `/ws/telnyx/{call_id}`	No
`--route-ref <ref>`	`voice-runtime`: runtime route or agent version to select	No
`--dry-run`	Preview without creating	No

Endpoint types: webhook, agent-runtime, queue, sip, email-forward, hosted-page, dead-letter, voice-runtime.

For webhook and agent-runtime types, the third argument is the URL. For an HTTP queue adapter, the third argument is the HTTPS adapter URL. Set queue_adapter explicitly to http or cloudflare and configure authentication. HTTP adapters must return a durable acceptance receipt with the supplied idempotency key; native SQS is not supported.

voice-runtime endpoints hand inbound Telnyx calls to an external voice-agent runtime (for example vbox): on call.initiated the Worker answers and starts bidirectional media streaming (both_tracks, RTP, L16 at 16 kHz) toward <runtime_url><stream_path>?stream_auth_token=<token>; no greeting is spoken and nothing is recorded. The stream token is resolved from the secret store at call time and travels only on the stream URL (verified by the runtime at the WebSocket handshake), never in Telnyx client_state; the API refuses inline tokens and non-TLS runtime URLs. Email and SMS events routed to a voice-runtime endpoint are dead-lettered with reason voice_runtime_requires_voice_channel.

`agentowl endpoint list`

agentowl endpoint list --tenant acme

Option	Description	Required
`--tenant <tenant>`	Tenant slug or ID	Yes

`agentowl endpoint inspect <endpoint_id>`

agentowl endpoint inspect ep_abc123

For voice-runtime endpoints the output also shows the derived stream_url_template, codec, and sample_rate.

`agentowl endpoint update <endpoint_id>`

agentowl endpoint update ep_abc123 --name "new-name"
agentowl endpoint update ep_abc123 --url https://new-url.example.com

Option	Description
`--name <name>`	New endpoint name
`--url <url>`	New URL (webhook/agent-runtime)
`--runtime-url <url>`	New runtime URL (voice-runtime)
`--route-ref <ref>`	New runtime route ref (voice-runtime)
`--stream-token-secret-ref <ref>`	New stream token secret reference (voice-runtime)

Uses optimistic concurrency control (If-Match with etag).

`agentowl endpoint signing prepare <endpoint_id>`

Generate a new signing secret, shown once, without changing the endpoint's active signing settings. Save the returned secret in your receiver. Generating another candidate invalidates the previous unactivated candidate.

agentowl endpoint signing prepare ep_... --json

`agentowl endpoint signing activate <endpoint_id> <key_id>`

Activate the prepared key after configuring your receiver for timestamp-bound v2 verification. This also applies to pending retries. When rotating, accept both keys during the transition. See webhook verification.

agentowl endpoint signing activate ep_... <key_id>

`agentowl endpoint delete <endpoint_id>`

agentowl endpoint delete ep_abc123 --confirm

Fails if any routes reference this endpoint. Delete the routes first.

Email bindings

Required role: platform-admin or tenant-admin (within scope).

`agentowl email bind <tenant> <address>`

Bind an email address to a tenant.

agentowl email bind acme support@acme.agentowl.dev --provider smtp

Option	Description	Default
`--provider <provider>`	`smtp` for workspace-subdomain addresses and operator-configured custom-domain addresses received by AgentOwl's SMTP server	`smtp`

Cloudflare Email Routing is reserved for AgentOwl operational addresses. Historical Cloudflare bindings remain readable but cannot be created or removed through this command.

`agentowl email inspect <binding_id>`

agentowl email inspect b_abc123

`agentowl email unbind <binding_id>`

agentowl email unbind b_abc123 --plan      # Preview
agentowl email unbind b_abc123 --confirm   # Execute

Messaging bindings (SMS/Voice)

Required role: platform-admin or tenant-admin (within scope).

`agentowl messaging bind <tenant>`

Bind a messaging number.

# Auto-assign a number with SMS capability
agentowl messaging bind acme --capability sms

# Bind a specific number with SMS and voice
agentowl messaging bind acme --number +15551234567 --capability sms voice

# Use a specific provider
agentowl messaging bind acme --provider telnyx --capability sms

Option	Description	Default
`--provider <provider>`	Messaging provider	`telnyx`
`--number <number>`	Specific phone number	Auto-assign
`--capability <cap...>`	Capabilities: `sms`, `voice`, `mms`	`sms`

Phone bindings require an active paid entitlement. Hosted upgrades are not currently self-service; contact support@agentowl.dev for phone availability before using these commands. In a configured deployment, reconciliation purchases and assigns a new number when --number is omitted; creating the binding alone does not prove provider provisioning succeeded. Sandbox billing does not grant production phone privileges.

`agentowl messaging import-number <tenant> <number>`

Import an existing phone number from your provider account.

agentowl messaging import-number acme +15551234567 --capability sms voice

Option	Description	Default
`--provider <provider>`	Messaging provider	`telnyx`
`--capability <cap...>`	Capabilities	`sms`

`agentowl messaging update <binding_id>`

Change a messaging binding's capabilities or number.

agentowl messaging update b_abc123 --capability sms voice mms

Option	Description
`--capability <cap...>`	Capabilities: `sms`, `voice`, `mms`
`--number <number>`	New phone number

`agentowl messaging inspect <binding_id>`

agentowl messaging inspect b_abc123

`agentowl messaging unbind <binding_id>`

agentowl messaging unbind b_abc123 --plan      # Preview
agentowl messaging unbind b_abc123 --confirm   # Execute

Routes

Required role: platform-admin or tenant-admin (within scope).

`agentowl route create`

Create a route connecting a binding to an endpoint.

agentowl route create \
  --tenant acme \
  --binding b_abc123 \
  --endpoint ep_def456 \
  --priority 100

Option	Description	Default	Required
`--tenant <tenant>`	Tenant slug or ID		Yes
`--binding <id>`	Binding ID		Yes
`--endpoint <id>`	Endpoint ID		Yes
`--priority <n>`	Priority (lower = first)	`100`	No
`--dry-run`	Preview without creating		No

`agentowl route list`

agentowl route list --tenant acme

`agentowl route inspect <route_id>`

agentowl route inspect r_abc123

`agentowl route update <route_id>`

agentowl route update r_abc123 --priority 50
agentowl route update r_abc123 --endpoint ep_new456
agentowl route update r_abc123 --fallback dead-letter

Option	Description
`--priority <n>`	New priority
`--endpoint <id>`	New endpoint ID
`--fallback <policy>`	`dead-letter`, `drop`, `quarantine`

`agentowl route delete <route_id>`

agentowl route delete r_abc123 --plan      # Preview
agentowl route delete r_abc123 --confirm   # Execute

Policies

Required role: platform-admin or tenant-admin (within scope).

`agentowl policy create <tenant> <name>`

agentowl policy create acme spam-filter --type content-filter

Option	Description	Required
`--type <type>`	Policy type	Yes

`agentowl policy list`

agentowl policy list --tenant acme

`agentowl policy inspect <policy_id>`

agentowl policy inspect pol_abc123

`agentowl policy update <policy_id>`

agentowl policy update pol_abc123 --name "new-name" --type new-type

`agentowl policy attach <policy_id>`

Attach a policy to one or more bindings.

agentowl policy attach pol_abc123 --binding b_abc123 --binding b_def456

`agentowl policy delete <policy_id>`

agentowl policy delete pol_abc123 --confirm

Events and logs

`agentowl events inspect <event_id>`

View details of a specific event.

agentowl events inspect evt_abc123

`agentowl events replay <event_id>`

Replay an event for testing or recovery.

agentowl events replay evt_abc123 --mode redrive-dispatch
agentowl events replay evt_abc123 --mode re-evaluate-route
agentowl events replay evt_abc123 --mode simulate

Mode	Description
`redrive-dispatch`	Enqueue the stored event; the consumer resolves current routes and endpoints
`re-evaluate-route`	Enqueue the stored event and resolve current routes and endpoints
`simulate`	Dry-run without actual dispatch

`agentowl logs tail <tenant>`

Tail recent events for a tenant.

agentowl logs tail acme
agentowl logs tail acme --channel email --limit 50

Option	Description	Default
`--channel <ch>`	Filter: `email`, `sms`, `voice`	All
`--limit <n>`	Number of events	`20`

`agentowl deadletter list`

List events that failed routing or delivery.

agentowl deadletter list --tenant acme

Audit log

`agentowl audit list`

Query the audit trail of administrative actions.

# Platform admin: all tenants
agentowl audit list

# Platform admin: specific tenant
agentowl audit list --tenant acme

# Tenant admin: must specify tenant
agentowl audit list --tenant acme

# Filter by operator
agentowl audit list --operator op_jane --since 2026-03-01T00:00:00Z

# Filter by resource type
agentowl audit list --tenant acme --resource binding --limit 100

Option	Description	Default
`--tenant <tenant>`	Filter by tenant (required for tenant-admin)
`--operator <id>`	Filter by operator ID
`--resource <type>`	Filter: `tenant`, `binding`, `endpoint`, `route`, `policy`, etc.
`--since <timestamp>`	ISO 8601 timestamp lower bound
`--limit <n>`	Max entries to return	`50`

Provider operations

`agentowl provider sync <tenant>`

Trigger a reconciliation job to sync desired state with providers (Telnyx, Cloudflare).

agentowl provider sync acme

`agentowl drift check <tenant>`

Check for drift between the desired state in AgentOwl and the actual state at providers.

agentowl drift check acme

Configuration management

`agentowl config publish <tenant>`

Publish the current desired state as a runtime config snapshot to KV.

agentowl config publish acme

`agentowl config inspect <tenant>`

View the currently published runtime config.

agentowl config inspect acme

`agentowl config diff <tenant>`

Compare the published runtime config with the tenant's current endpoints, bindings, routes, and policies. Use it to see what config publish would change.

agentowl config diff acme

Declarative config commands

`agentowl validate -f <file>`

Validate a desired-state config file without making changes.

agentowl validate -f acme.yaml

`agentowl plan -f <file>`

Validate and compute a diff showing what would change.

agentowl plan -f acme.yaml

`agentowl apply -f <file>`

Apply a desired-state config. Without --auto-approve, shows the plan and exits.

agentowl apply -f acme.yaml                # Shows plan only
agentowl apply -f acme.yaml --auto-approve  # Applies changes

`agentowl diff -f <file>`

Show the diff between a config file and current server state.

agentowl diff -f acme.yaml

Deployments

Required role: platform-admin only.

`agentowl deploy worker <role>`

Promote an already uploaded, tested Cloudflare Worker version for a configured role. Building/uploading artifacts, Pages deployment, and database migrations remain separate release steps. The server requires a configured role-to-script mapping and a stored deployment credential.

agentowl deploy worker api --revision 023e105f-2a42-4f8b-a1c1-73f6a2a30c0f

Option	Description
`--revision <uuid>`	Required: uploaded Cloudflare Worker version UUID

Valid roles: api, email-ingress, sms-ingress, voice-ingress, queue-consumer, reconciler.

Diagnostics

`agentowl doctor <tenant>`

Run health and diagnostics checks.

agentowl doctor acme

Checks:

API connectivity
Tenant state
Provider drift
Published config status

On this page