Install the Agoralia CLI, log in with a CLI token, and drive the gated agent surface — pages, approvals, activity, connections, and calls.

CLI

agoralia is a thin, gated client over the Agoralia agent surface. Every call is gated server-side and tagged surface=cli in the audit log. Dangerous actions return a guided approval required response with the id and how to retry.

Install

Install from PyPI:

pip install agoralia-cli

This installs the agoralia command.

Log in

The CLI authenticates with an OAuth Bearer token (the same gated surface MCP uses), not an ag_ REST key. Mint a token in Dashboard → API Keys → "CLI token", then:

agoralia auth login --token <CLI_TOKEN>

The token is stored in ~/.agoralia/credentials.json (chmod 600). The default API URL is https://api.agoralia.app — override with --api-url or AGORALIA_API_URL.

Alternatively, skip storing it and export the token per session:

export AGORALIA_TOKEN=<CLI_TOKEN>

Token resolution order: --token flag → AGORALIA_TOKEN env → stored credentials.

The CLI hits the gated agent surface (/pages, /approvals, /actions, /mcp-connections), not the /api/v1 REST namespace. See Authentication.

Manage the session

agoralia auth status   # show whether you're authenticated, the API URL, and token source
agoralia auth logout   # remove the stored token

Commands

pages — generative dashboard pages

agoralia pages list
agoralia pages get <slug>
agoralia pages create spec.json   # path to a view-spec JSON file

approvals — the human-go queue

agoralia approvals list
agoralia approvals decide <id> approved   # or: denied

activity — audit of agent actions

agoralia activity --limit 50

connections — remote MCP servers the copilot can use

agoralia connections list
agoralia connections connect <name> <url> \
  --auth-token <BEARER> \
  --allowed-tool list_agents --allowed-tool get_agent
agoralia connections disconnect <id>

Omit --allowed-tool to allow all tools on the connected server. The --auth-token is stored encrypted server-side.

call — generic gated request to any route

An escape hatch to any gated route:

agoralia call GET /campaigns
agoralia call POST /campaigns/<id>/start --approval-id <id>
agoralia call POST /agents --data '{"name":"My agent"}'
agoralia call POST /agents --data @agent.json    # @ reads a JSON file

Approvals and the gate

Risk-tiered actions are blocked until a human approves them. When that happens the CLI prints the approval_id and remediation steps. Approve it (agoralia approvals decide <id> approved, or in the dashboard), then retry with the granted id:

agoralia --approval-id <APPROVAL_ID> call POST /campaigns/<id>/start

CLI

CLI