agoralia-cli

The Agoralia CLI — the third agent surface (alongside MCP and the REST API) for running compliant AI voice campaigns. It's a thin client over the already-gated REST API: same policy, same human-approval flow, same audit. It adds nothing privileged — the gate lives server-side; the CLI just speaks HTTP to it and renders the guided errors it returns.

Every call is tagged X-Agent-Surface: cli, so the action audit records that it came from the CLI.

Install

pip install agoralia-cli

Authenticate

The CLI uses a Bearer token (the same kind the MCP surface uses).

export AGORALIA_TOKEN=...                          # your Agoralia access token
export AGORALIA_API_URL=https://api.agoralia.app   # optional (defaults to localhost:8000)

Usage

# Generative dashboard pages (the agent composes a view; you see it at /pages/<slug>)
agoralia pages list
agoralia pages get q2-reactivation-calls
agoralia pages create ./spec.json

# Human "go" queue — approve/deny dangerous agent actions
agoralia approvals list
agoralia approvals decide <approval-id> approved

# Read-only audit of what your agents did
agoralia activity --limit 50

# Generic escape hatch to any gated route
agoralia call GET /campaigns
agoralia call POST /campaigns/<id>/start --data '{}'

The approval flow

Dangerous actions (launching a campaign, spending, deleting) are gated. When you hit one without an approval, the CLI tells you exactly what to do:

$ agoralia call POST /campaigns/abc/start
⚠  Approval required before this action can run.
   approval_id: appr_123
   → A human must approve it (POST /approvals/{id}/decide), then retry with header X-Approval-Id.
   Once approved, retry with: --approval-id appr_123

# a human approves it…
$ agoralia approvals decide appr_123 approved

# …then retry
$ agoralia call POST /campaigns/abc/start --approval-id appr_123

(Approval enforcement is controlled server-side by the AGENT_APPROVAL_ENABLED flag.)

Development

pip install -e .
python -m pytest tests/
python -m agoralia_cli --help   # same as the `agoralia` command