@animocabrands/minds-cli

Agent-first CLI for the Hello Minds Builder API (api.build) — JSON stdout, predictable exit codes, and copy-pasteable --help examples for automation.

Get started: Minds CLI guide on build.hellominds.ai

Requirements: Node.js ≥ 22.

Install

# Global (human PATH)
npm install -g @animocabrands/minds-cli

# No global install (agents, CI, sandboxes)
npx @animocabrands/minds-cli@latest <command>

Authentication

No minds login. Create a Builder API key at build.hellominds.ai/console, then set:

export MINDS_BUILDER_API_KEY=your_key_here

Or pass --builder-api-key <key> (legacy alias: --access-key). The CLI also loads .env from the current working directory.

Bazaar commands (minds bazaar …) are public catalog routes — no API key required.

Output

Default stdout is one JSON object per command:

| Outcome | Shape | | ----------------- | ------------------------------------------------------------------- | | List success | { "ok": true, "items": [...] } | | Singleton success | { "ok": true, "<resource>": T } | | Failure | { "ok": false, "error": "...", "message": "...", "hint?": "..." } |

Use --pretty for indented JSON. minds events prints NDJSON (one SSE object per line, no wrapper). Diagnostics go to stderr (info:, warn:, error:).

Exit codes

| Code | Meaning | | ---- | ----------------------------------------- | | 0 | success | | 2 | user error (bad args, invalid flags, 4xx) | | 3 | server / timeout / network | | 4 | auth (missing key) | | 5 | rate limit (429) |

Quick start

minds doctor
minds list
MIND_ID=$(minds list | jq -r '.items[0].mindId')
minds chat create --mind "$MIND_ID" --alias main
minds send main "Hello" --wait --timeout 120000

Resolve Mind UUIDs with minds list | jq — --mind flags accept UUID only.

Commands

Doctor & account

| Command | Auth | Description | | -------------- | -------- | ------------------------------------------------------- | | minds doctor | optional | api.build ping, key check, messaging probe, CLI version | | minds list | yes | List Minds (mindId, name) |

Messaging

| Command | Description | | ------------------------------------------------- | ----------------------------------------------------------------- | | minds chat list | List conversations | | minds chat show <alias> | Conversation detail (--history-limit N) | | minds chat create --mind <uuid> --alias <alias> | Create or ensure conversation | | minds send <alias> [text] | Send message (--wait, --timeout <ms>, --attachments <file>) | | minds history <alias> | Message history | | minds events [alias] | SSE stream as NDJSON |

Mind replies are often slow — use --timeout 180000 or minds history <alias> after a timeout.

Cognition balance

| Command | Description | | ---------------------------------------------------- | -------------------------- | | minds usage show --mind <uuid> [--interval 1d] | Cognition spend over time | | minds usage by-tool --mind <uuid> [--interval day] | Spend breakdown by tool | | minds cognition balance --mind <uuid> | Per-Mind cognition balance |

Interval enums differ per subcommand — invalid values exit 2 with a hint before any HTTP call.

Mind status

| Command | Description | | ---------------------------------- | ----------------------------------------------- | | minds mind show --mind <uuid> | Full Mind details (walletAddress, chain, …) | | minds mind disable --mind <uuid> | PATCH { isEnabled: false } | | minds mind enable --mind <uuid> | PATCH { isEnabled: true } |

Idempotent — safe to retry.

Bazaar (public catalog)

| Command | Description | | ------------------------------------ | ------------------------------- | | minds bazaar search <query> | Merged skills + apps search | | minds bazaar skills list | List or search skills | | minds bazaar skills show <skillId> | Skill detail | | minds bazaar apps list | List or search apps | | minds bazaar apps show <appId> | App detail (includes tools[]) |

Search flags: --max (1–200), --sort equipped|name|newest, --tier wild|verified (apps), --provider <slug> (client-side on apps). Search auto-fetches up to 200 rows internally. Browse without --search returns the first catalog slice with truncated: true when more rows exist.

Circles (human collaborators)

| Command | Description | | ----------------------------------------------------------- | ---------------------------------------------------- | | minds circle show --mind <uuid> | Members for one Mind (steward + human collaborators) | | minds circle list | All circles (N+1: one GET per Mind) | | minds circle add --mind <uuid> --email <e> [--email …] | Add collaborators (human emails documented today) | | minds circle remove --mind <uuid> --email <e> [--dry-run] | Remove collaborators |

Email rules: the supported workflow today is external human addresses (e.g. [email protected]). The steward is already in the circle. Mind platform emails (@hellominds.ai) are not documented for builders yet — if the API adds Mind-to-Mind support later, the same commands apply; always check result.items[].action and minds circle show.

After add/remove, check result.summary, result.items[].action, and minds circle show.

jq recipes

minds list | jq '.items[] | {mindId, name}'
minds chat list | jq '.items[].alias'
minds send main "hi" --wait | jq '.reply.messageText'
minds cognition balance --mind "$MIND_ID" | jq '.balance.cognition'
minds bazaar search "workflow" --max 10 | jq '.skills.items[].name'
minds circle list | jq '.items[] | {mindId, memberCount: (.members | length)}'

Global flags

| Flag | Description | | ------------------------- | ----------------------------------- | | --pretty | Pretty-print JSON stdout | | --builder-api-key <key> | Override MINDS_BUILDER_API_KEY | | --quiet | Suppress info diagnostics on stderr | | --no-color | Disable ANSI colors on stderr | | -V, --version | CLI version |

Every subcommand has minds <group> <subcmd> --help with Examples: — e.g. minds usage by-tool --help. Multi-segment help also works: minds help usage by-tool.

Library

Programmatic use? See @animocabrands/minds-client-lib — same api.build routes without the JSON envelope.

License

UNLICENSED — private alpha tooling.