CLI

allerto is a single Node.js file with no dependencies (Node 18 or newer). It talks to the public API, so it can do everything the API can.

#Install

npm install -g https://api.allerto.cloud/cli/allerto-cli.tgz
allerto --version

Without npm: curl -fsSL https://api.allerto.cloud/cli/allerto.mjs -o ~/.local/bin/allerto && chmod +x ~/.local/bin/allerto.

#Log in

Create a key in the console (Numbers and developers → API keys), then:

allerto login                 # prompts for the key, checks it, stores it
allerto whoami                # account · LIVE or TEST · key label

The key is saved in ~/.config/allerto/config.json with permissions 600. Other ways to pass it, in order of precedence: --key, ALLERTO_API_KEY, the saved profile. Keep several accounts or modes with --profile:

allerto login --profile test
allerto calls list --profile test

In CI, set ALLERTO_API_KEY as a secret and skip login.

#Agents as files

allerto agents pull <id> -o reminder.json      # draft + id + revision
$EDITOR reminder.json
allerto agents validate reminder.json
allerto agents push reminder.json              # saves the draft, updates revision in the file
allerto agents push reminder.json --publish    # save and publish
allerto agents push new-agent.json --client ACME   # no "id": creates it

If someone changed the agent in the meantime, push fails with revision_conflict. Pull again, or pass --force to overwrite with your file.

#Reference

allerto 2.1.0 — voice agents that answer and place phone calls

Usage: allerto <command> [options]

Account
  login [--key <key>]                 Save an API key (created in the portal: Numbers and developers)
  logout                              Forget the key of the current profile
  whoami                              Show account and mode (live or test)

Agents
  agents list [--type inbound|outbound]
  agents get <id> [--published]
  agents pull <id> [-o file]          Write the draft as a JSON file (keeps id and revision)
  agents push <file> [--publish] [--client <ref>] [--force]
                                      Create (no "id") or update the draft from a file
  agents validate <file>              Check a file against every rule, without saving
  agents publish <id>                 Publish the current draft as a new version
  agents preview <id> [--input k=v]… [--draft]
  agents archive <id>
  agents schema                       Print the agent JSON Schema
  agents mcp-token <id> [--token t] [--remove]
                                      Store (or remove) the bearer token for the agent's MCP server
  agents mcp-test <id>                List the tools the agent gets from its MCP server

Calls
  calls create --agent <id> --to <+39…> [--input k=v]… [--ref <r>] [--at <iso>]
               [--attempts n] [--idempotency-key k] [--wait]
  calls list [--direction d] [--agent id] [--outcome o] [--status s] [--since 1d|iso] [--limit n]
  calls get <id> [--transcript]
  calls watch <id>                    Follow a call until it ends
  calls cancel <id>

Campaigns
  campaigns create --agent <id> --csv <file> [--name n] [--at iso] [--attempts n] [--concurrency n]
                                      CSV: a "to" column (or phone/telefono/numero), optional
                                      "reference", every other column is an input
  campaigns list | get <id> | pause <id> | resume <id> | cancel <id>

Account settings
  numbers list | numbers route <number-id> --agent <id>
  suppressions list | add <number> [--reason r] | remove <number>
  webhook-secret rotate
  events list
  usage [--period YYYY-MM]
  openapi                             Print the OpenAPI specification

AI agents
  mcp                                 Run a local MCP server on stdio (proxy to /mcp)

Global options
  --json              Machine-readable output (stable)
  --profile <name>    Use another saved profile (default: "default")
  --api-url <url>     Default https://api.allerto.cloud (env ALLERTO_API_URL)
  --key <key>         Use this key instead of the saved one (env ALLERTO_API_KEY)

Exit codes: 0 ok, 1 error, 2 usage error.

#Output and exit codes

Human-readable tables by default; --json prints the API response unchanged, for jq and scripts. Exit code 0 on success, 1 on API or network errors, 2 on usage errors. Errors print the API's stable code, for example Error: missing_inputs: Missing inputs: amount.