Aima CLI

The Aima CLI (aima) is an AWS-CLI-shaped command-line client for AIMA Labs. It drives the /api/cli REST API — the same surface exposed as MCP tools for Claude, Cursor, and Codex.

Grammar: aima <noun> <verb>. Most commands are thin wrappers over a single API endpoint. A few composites (init, status, onboard) orchestrate multiple calls client-side.

Install

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

Homebrew (macOS/Linux):

brew install stepacool/tap/aima

uv / pipx (isolated install on your PATH):

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

pip:

pip install aimalabs-cli

Run once without installing (does not add aima to PATH):

uvx --from aimalabs-cli aima --help

Upgrade with uv tool upgrade aimalabs-cli, pipx upgrade aimalabs-cli, or brew upgrade aima.

Quick start

aima init                 # API key wizard → ~/.aima/config.json
aima status               # verify config and connectivity
aima voices list          # browse voices
aima onboard              # guided voice or WhatsApp walkthrough

Manual flow:

aima campaigns create \
  --title "Q2 outbound" \
  --company-name "Acme Corp" \
  --voice-id 42 \
  --field "budget:string:Ask their monthly budget."
 
aima leads add-test --campaign-id 17 --lead "Jane Doe:+15551234567"
aima calls dispatch 501 --yes
aima calls status 501 --poll

Configuration

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

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

Get an API key from Settings → Organization → Developers → API keys in the dashboard.

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

If no API key is configured, every command except aima init, aima config …, and aima --help exits with code 3.

Output modes

• Human (default): Rich tables and key/value blocks. List picks use arrow-key menus.
• --json: Raw API response body to stdout only. Status and errors go to stderr.
• Auto-JSON: When stdout is not a TTY, JSON is emitted automatically. Override with --no-json.

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

Exit codes

Commands

Setup

Config

Voices

Agents

--system-prompt accepts a literal string or @path/to/file.

Campaigns

Create flags (voice):

aima campaigns create \
  --title "Q2 outbound" \
  --company-name "Acme Corp" \
  --voice-id 42 \
  --agent-name "Stefan" \
  --language en \
  --system-prompt @prompts/agent.txt \
  --extra-context "Mention the summer promo." \
  --field "budget:string:Ask their monthly budget." \
  --field "tier:enum:Which tier?:values=bronze,silver,gold"

WhatsApp / hybrid flags:

# Outbound WhatsApp
aima campaigns create \
  --title "WA demo invites" \
  --company-name "Acme Corp" \
  --campaign-type whatsapp \
  --whatsapp-credentials-id 12 \
  --template-name hello_world \
  --template-language en
 
# Inbound-only WhatsApp
aima campaigns create \
  --title "WA support line" \
  --company-name "Acme Corp" \
  --campaign-type whatsapp \
  --whatsapp-credentials-id 12 \
  --inbound-only

Extraction fields: repeat --field title:type:description. Types: string, integer, float, boolean, date, datetime, enum, json, array, calendar_appointment, file. For enum, append :values=a,b,c.

YAML body: --from-yaml body.yaml supplies the full request JSON shape; explicit flags override YAML values.

Leads

leads initiate requires an outbound WhatsApp campaign (template_name set, not --inbound-only). Consumes WhatsApp lead quota.

Calls

Polling: voice terminates when latest_call.ended_at is set. WhatsApp terminates when latest_conversation.latest_message_status is sent or delivered, or conversation status advances past not_started / failed_to_start.

Phone numbers

Flow: phones available → note phone_number_id → phones rent → phones list shows assignment_id for release.

WhatsApp credentials

Connect flow:

1. CLI creates a connect session (POST /api/cli/whatsapp/connect-sessions).
2. Opens {DASHBOARD_URL}/connect/whatsapp/{session_id} (Meta FB JS SDK embedded signup — not a localhost OAuth redirect).
3. Polls every ~3s until completed, failed, or timeout.
4. embedded = new WhatsApp Business API number. coexistence = link an existing Business app.

Run aima whatsapp validate <id> before creating campaigns.

Usage

Onboard walkthrough

aima onboard is interactive only (no --json). It applies a minimal-confirmation policy: only prompts before calls dispatch, leads initiate, and large CSV uploads.

Voice path

1. Config check (init if missing).
2. Pick a voice from a select menu.
3. Prompt for campaign title, company name, optional system prompt and fields.
4. Create voice campaign.
5. Add one test lead.
6. Confirm, then dispatch call.
7. Poll until call ends; print transcript/summary.

WhatsApp path

1. Pick existing credentials or start browser connect (embedded / coexistence).
2. Validate credentials.
3. Template table + select: outbound template, inbound-only, or fallback when no approved templates exist.
4. Create WhatsApp campaign.
5. Inbound-only: print display_phone_number and instruct user to message it.
6. Outbound: add test lead → confirm leads initiate → poll latest_conversation up to 5 minutes.

For AI agents and CI

• Set AIMA_OUTPUT=json or pass --json for parseable stdout.
• Errors print the backend detail field to stderr with stable exit codes.
• aima <noun> --help and aima <noun> <verb> --help document every flag.
• Destructive or billable actions (calls dispatch, leads initiate, phones rent, large CSV) need --yes in non-interactive contexts.
• The same API key powers the MCP server for chat-based control.

Related

• Aima MCP — use the same API from Claude, Cursor, or Codex
• Campaigns — dashboard campaign setup
• Integrations — Google Calendar and agent MCP bindings
• Billing — plan limits that aima usage view reflects