Metadata-Version: 2.4
Name: agoralia-cli
Version: 0.1.0
Summary: Agoralia CLI — the gated agent surface (MCP · REST · CLI) for compliant AI voice campaigns
Project-URL: Homepage, https://agoralia.app
Project-URL: Documentation, https://docs.agoralia.app
Project-URL: Source, https://github.com/giacomocavalcabo/agoralia-v2
Author: Agoralia
License-Expression: MIT
Keywords: agent,agoralia,ai,cli,mcp,voice
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Telephony
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# 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

```bash
pip install agoralia-cli
```

## Authenticate

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

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

## Usage

```bash
# 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:

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

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