aimalabs-cli

aima — AIMA Labs CLI

An AWS-CLI-shaped command line for AIMA Labs. Drive voice and WhatsApp campaigns — set up a campaign, add leads, place outbound calls, and watch their status — from a terminal, a CI pipeline, or an AI agent.

The grammar is aima <noun> <verb>. It's a thin, dependency-light wire-protocol client over the /api/cli REST surface: every command is a 1:1 wrapper over an endpoint, except a few client-side composites (init, status, onboard).

Install

The PyPI package is aimalabs-cli; the command it installs is aima.

Homebrew (macOS/Linux):

brew install stepacool/tap/aima

uv / pipx — isolated install onto your PATH (provides the aima command):

uv tool install aimalabs-cli      # or: pipx install aimalabs-cli

pip:

pip install aimalabs-cli

Run once without installing (ephemeral — does not add aima to your PATH). Because the package and command names differ, uvx needs --from:

uvx --from aimalabs-cli aima --help    # not: uvx aimalabs-cli

Upgrade or remove an isolated install later with uv tool upgrade aimalabs-cli (or pipx upgrade / brew upgrade aima) and the matching uninstall.

Quick start

aima init                 # prompts for your API key, validates it, writes ~/.aima/config.json (0600)
aima voices list          # browse available voices
aima onboard              # guided: voice → campaign → test lead → real call → live status

Or do it by hand:

aima campaigns create \
  --title "Q2 outbound" --company-name "Acme Corp" \
  --voice-id 42 \
  --field "budget:string:Ask the prospect their monthly budget." \
  --field "plan:enum:Which plan are they on?:values=free,pro,enterprise"

aima leads add-test --campaign-id 17 --lead "Jane Doe:+15551234567"
aima calls dispatch 501 --yes
aima calls status 501 --poll

# Manage agents and tweak a campaign after the fact:
aima agents list
aima agents create --name "Stefan" --company-name "Acme Corp" --voice-id 42
aima agents update 9 --system-prompt @prompts/stefan.txt
aima campaigns update 17 --title "Q2 outbound (v2)" --agent-id 9 --extra-context "Mention the summer promo."

Configuration

Config lives at ~/.aima/config.json (mode 0600):

{ "base_url": "https://api.aimalabs.io", "api_key": "api_..." }

Environment variables override the file:

Manage it directly:

aima config show          # api_key is masked as api_…<last4>
aima config set base_url https://staging.aimalabs.io
aima config clear

Output modes

• Human (default): rich tables and key/value blocks. The API key is always masked.
• --json: raw response body to stdout, nothing else. The exit code carries success/failure.
• Auto: when stdout is not a TTY, JSON is emitted automatically. Override with --no-json.
• AIMA_OUTPUT=json behaves like --json.

Status lines, prompts, and errors go to stderr, so --json stdout stays clean and pipeable:

aima campaigns list --json | jq '.[].campaign_id'

Commands

Defining extraction fields

--field is repeatable. Each token is title:type:description:

--field "budget:string:Ask their monthly budget."
--field "meeting:calendar_appointment:Book a demo."
--field "tier:enum:Which tier?:values=bronze,silver,gold"

Types: string, integer, float, boolean, date, datetime, enum, json, array, calendar_appointment, file. Enum types require the trailing :values=....

--system-prompt and --extra-context accept a literal string or @path/to/file to read from disk. The whole request body can also be supplied with --from-yaml body.yaml; explicit flags override values from the YAML.

Exit codes

For AI agents

aima is designed to be driven by coding agents. Tips:

• Set AIMA_OUTPUT=json (or pass --json) for deterministic, parseable output.
• Every error prints the backend's detail to stderr and uses a stable exit code.
• aima <noun> --help and aima <noun> <verb> --help describe every flag.
• Calls that cost money (calls dispatch, large upload-csv) require --yes in non-interactive contexts.

Development

uv pip install -e ".[dev]"
pytest
ruff check src

License

MIT