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=jsonbehaves 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
detailto stderr and uses a stable exit code. aima <noun> --helpandaima <noun> <verb> --helpdescribe every flag.- Calls that cost money (
calls dispatch, largeupload-csv) require--yesin 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.