Skip to main content

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:

Variable Effect
AIMA_API_KEY Override api_key.
AIMA_BASE_URL Override base_url (self-hosted / staging).
AIMA_CONFIG Use an alternate config-file path.
AIMA_OUTPUT=json Force machine-readable output.

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

Command What it does
aima init First-run wizard: prompt, validate against the API, write config.
aima status Show config and probe that the key still works.
aima config show | set | clear Manage local config.
aima voices list [--language] [--provider] [--voice-type] [--no-active] List voices (active by default).
aima agents list [--limit N] List agents, newest first.
aima agents get <agent_id> Show one agent, including its system prompt.
aima agents create --name N --company-name C [--language] [--system-prompt] [--voice-id] Create a reusable agent.
aima agents update <agent_id> [--name] [--company-name] [--language] [--system-prompt] [--voice-id] Update an agent (only the flags you pass).
aima campaigns list [--active|--inactive] [--limit N] List campaigns, newest first.
aima campaigns create ... Create a campaign + agent + extraction fields atomically.
aima campaigns update <campaign_id> [--title] [--agent-id] [--extra-context] [--active|--inactive] Retitle, reassign the agent, or edit the prompt.
aima leads add-test --campaign-id ID --lead NAME:E164 Add test leads (no dispatch).
aima leads upload-csv --campaign-id ID --file PATH ... Bulk-create leads from CSV (or stdin via --file -).
aima calls dispatch <lead_id> Place a real outbound call (confirms unless --yes).
aima calls status <lead_id> [--poll] Latest call status + extracted values; --poll until it ends.
aima onboard Interactive end-to-end walkthrough.

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

Code Meaning
0 Success.
1 User error — bad flags, validation, or a 4xx from the API (detail printed to stderr).
2 Server / network error — a 5xx or a transport failure.
3 Missing or invalid config (no API key, unreadable file).

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

Metadata

Release files for aimalabs-cli 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aimalabs-cli 0.3.0
File Size Uploaded Provenance Actions
aimalabs_cli-0.3.0.tar.gz 50.7 kB With provenance Details for aimalabs_cli-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aimalabs-cli 0.3.0
File Interpreter ABI Platform Actions
aimalabs_cli-0.3.0-py3-none-any.whl Python 3 none any Details for aimalabs_cli-0.3.0-py3-none-any.whl

Total release size: 79.5 kB

Release files / aimalabs_cli-0.3.0.tar.gz

Download URL aimalabs_cli-0.3.0.tar.gz
Size 50.7 kB
Tags Source
SHA-256 checksum
How to use checksums
688d13f71e179c33329169cdfe1e0cf66905c534e718702d5cad27ca1f93735d
BLAKE2b-256 checksum
How to use checksums
cf27814c194be0690a876e8699defec52d7ff4a6f0b820cf25a52a8be2152de0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 17, 2026.

Transparency log

Release files / aimalabs_cli-0.3.0-py3-none-any.whl

Download URL aimalabs_cli-0.3.0-py3-none-any.whl
Size 28.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e6338476cdb87c65f82c759fa82c736dd4e32411e51ea99c665d7ddf8bf695b8
BLAKE2b-256 checksum
How to use checksums
67f76d99188ab745c6d3a077636361fd14dbb2a65dc7f94be948a7cdcd7f52c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 17, 2026.

Transparency log

Security for aimalabs-cli 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aimalabs_cli-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page