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

Authentication

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

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

Option	Description	Default
`--token <token>`	API bearer token
`--url <url>`	API base URL	`http://localhost:8787`

Environment variable overrides (take precedence over config file):

Variable	Description
`AGENTOWL_API_TOKEN`	Bearer token
`AGENTOWL_API_URL`	API base URL

`agentowl version`

Show CLI and server version.

agentowl version

`agentowl compat check`

Check CLI/server compatibility.

agentowl compat check

Tenants

Required role: platform-admin for create. Both roles for 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.

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 queue my-queue events-queue --tenant acme

Option	Description	Required
`--tenant <tenant>`	Tenant slug or ID	Yes
`--dry-run`	Preview without creating	No

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

For webhook and agent-runtime types, the third argument is the URL. For queue types, the third argument is the queue name.

`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

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

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

`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.com
agentowl email bind acme support@acme.com --provider cloudflare

Option	Description	Default
`--provider <provider>`	Email provider	`cloudflare`

`agentowl email domain add <tenant> <domain>`

Add a domain for catch-all email routing. Creates a binding for *@<domain>.

agentowl email domain add acme acme.com

Option	Description	Default
`--provider <provider>`	Email provider	`cloudflare`

`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`
`--number-strategy <s>`	Assignment strategy	`assign`

`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 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`	Re-dispatch to the same endpoint
`re-evaluate-route`	Re-evaluate routing rules and dispatch
`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

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

Trigger a worker role deployment.

agentowl deploy worker api
agentowl deploy worker sms-ingress --revision v1.2.3

Option	Description
`--revision <tag>`	Deployment revision tag

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

CLI Reference

On this page