Get Started

Minds CLI

The fastest way to get value from Builder Tools is a coding agent with shell access. Install once, set your API key, then ask it to run minds commands for you.

The Minds CLI is a JSON-first terminal interface to the Builder API . Every command prints one object on stdout; every subcommand ships copy-paste examples in --help. That is deliberate: Cursor, Claude Code, Codex, or any agent with a terminal can discover commands, run them, pipe through jq, and report back in plain language while you stay in your editor.Install once, set MINDS_BUILDER_API_KEY, then ask your agent, for example:

"List my Minds and show full detail for the first one"
"How much cognition did my Mind use in the last week?"
"Which tools consumed the most cognition yesterday?"
"Search the Bazaar for Notion apps and show what tools each one exposes"
"Add colleague@company.com to my Mind's circle"

Behind those prompts the agent runs minds list, minds mind show, minds usage show --interval 1w, minds usage by-tool --interval day, minds bazaar apps list --search "notion", minds circle add, and so on. You do not need to memorize flags, minds <command> --help is the source of truth your agent can read. Diagnostics and truncation hints go to stderr; stdout stays clean JSON for scripts and CI.Complete Account setup first (Mind + Builder API key), then install below or hand the same commands to your agent.

Install

Requires Node 22+.

npm install -g @animocabrands/minds-cli

Update after a new release:

npm install -g @animocabrands/minds-cli@latest

Agents, sandboxes, and CI

Your coding agent can use the same install paths below. For sandboxes, ephemeral environments, or CI, skip the global install:

npx @animocabrands/minds-cli@latest doctor --pretty
npx @animocabrands/minds-cli@latest list

The CLI reads MINDS_BUILDER_API_KEY from your shell environment. Any of these work:

export MINDS_BUILDER_API_KEY=your_key_here
minds doctor --pretty

MINDS_BUILDER_API_KEY=your_key_here minds doctor --pretty

A .env file in your project directory also works, the CLI loads it when the variable is not already set in the shell. Pass --builder-api-key when scripting:

npx @animocabrands/minds-cli@latest chat list --builder-api-key "$MINDS_BUILDER_API_KEY"

GitHub Actions

Use the CLI in CI the same way as locally: npx, Node 22+, and MINDS_BUILDER_API_KEY as a repository secret. JSON stdout pipes cleanly into jq for summaries, gates, or Slack notifications. Example - weekly cognition usage for your first Mind (runs Mondays 09:00 UTC; also trigger manually):

name: Weekly cognition usage
 
on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:
 
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
 
      - name: Cognition usage and balance
        env:
          MINDS_BUILDER_API_KEY: ${{ secrets.MINDS_BUILDER_API_KEY }}
        run: |
          npx @animocabrands/minds-cli@latest doctor
          MIND_ID=$(npx @animocabrands/minds-cli@latest list | jq -r '.items[0].mindId')
          npx @animocabrands/minds-cli@latest usage show --mind "$MIND_ID" --interval 1w
          npx @animocabrands/minds-cli@latest cognition balance --mind "$MIND_ID" | jq '.balance.cognition'

Verify and explore

Run these yourself for a quick sanity check, or ask your agent to run them after install:

minds doctor --pretty
minds --help
minds chat --help
minds usage by-tool --help

Every subcommand includes copy-paste Examples in its --help output. For multi-segment commands, the canonical pattern is minds <group> <subcmd> --help (for example minds usage by-tool --help). These also work: minds help usage by-tool and minds usage --help by-tool. Authenticated requests require X-Api-Key with your Builder API key. X-Access-Key is deprecated, do not use it on HTTP requests. The CLI reads MINDS_BUILDER_API_KEY (or --builder-api-key; deprecated CLI flag --access-key) and sends X-Api-Key only. Default stdout is one JSON object { ok: true, … }; diagnostics go to stderr. minds events is the exception, it prints NDJSON lines. If minds doctor reports a missing key, return to Account setup to create a key, then export MINDS_BUILDER_API_KEY=… (or add it to .env in your project).

List your Minds

minds list calls the Builder API for every Mind on your account, mindId, name, model, species, and related fields. You do not need to copy IDs from the console. After minds doctor passes:

minds list --pretty

Pipe to jq when scripting:

minds list | jq '.items[] | {mindId, name}'

Mind details

minds list returns summary fields. For full detail: email, wallet address, chain, species, isEnabled, and more. Use minds mind show. Set $MIND_ID to the Mind UUID from minds list (not the display name):

MIND_ID=$(minds list | jq -r '.items[0].mindId')
minds mind show --mind "$MIND_ID"
minds mind show --mind "$MIND_ID" | jq '.mind.walletAddress'

Response shape: { ok: true, mind: { … } }.

Cognition balance and usage

Minds consume cognition when they reason, run tools, and carry out autonomous tasks, not only when you message them. Check cognition usage and the remaining cognition balance per Mind; pass a mindId from minds list.

MIND_ID=$(minds list | jq -r '.items[0].mindId')
 
minds usage show --mind "$MIND_ID"
minds usage show --mind "$MIND_ID" --interval 1w
minds usage by-tool --mind "$MIND_ID" --interval day
minds cognition balance --mind "$MIND_ID"

usage show reports cognition usage over time. usage by-tool breaks usage down per tool with a summary and a timeline. Accepted intervals differ by command: usage show accepts 1m, 5m, 15m, 1h, 1d, 1w, 1M; usage by-tool accepts hour, day, week, month only. The CLI validates the interval before calling the API, so an invalid value exits 2 with the accepted set in the hint. Cognition powers a Mind's reasoning, tool use, and autonomous work. Check the remaining cognition balance with cognition balance:

minds cognition balance --mind "$MIND_ID" | jq '.balance.cognition'

Enable and disable a Mind

Pause or resume a Mind as needed:

minds mind disable --mind "$MIND_ID"
minds mind enable --mind "$MIND_ID"

Power down a Mind when its cognition balance is exhausted:

minds cognition balance --mind "$MIND_ID" | jq -e '.balance.cognition <= 0' && minds mind disable --mind "$MIND_ID"

Circles

A Mind's circle is the set of human collaborators who can interact with it. List the members for one Mind, or across every Mind on your account:

minds circle show --mind "$MIND_ID"
minds circle list | jq '.items[] | {mindId, memberCount: (.members | length)}'

Add or remove collaborators by email. --email is repeatable:

minds circle add --mind "$MIND_ID" --email someone@company.com --email peer@company.com
minds circle remove --mind "$MIND_ID" --email someone@company.com
minds circle remove --mind "$MIND_ID" --email someone@company.com --dry-run

Circles accept human collaborator emails only. Mind-to-mind circle membership is not supported. circle add activates new members by default; pass --dry-run on remove to preview which emails would be removed without running the command. Response shapes differ by verb: circle show returns { ok: true, mindId, items: CircleMember[] }; add and remove return { ok: true, mindId, result: { items, summary } } with per-email outcomes. Duplicate emails on circle add may return action: "exists" or "already_in_circle", the CLI treats these as success and warns on stderr only when the mutation had no net effect.

Bazaar catalog

The Bazaar is the public catalog of skills and apps. Bazaar commands do not require a Builder API key, they work in CI and sandboxes without MINDS_BUILDER_API_KEY set. The same catalog is available in the client library as client.bazaar.*. Use Bazaar for ID discovery (skillId, appId), then equip those IDs on a Mind with minds mind skills|apps (see below). List items may include equippedCount, how many Minds have equipped that skill or app platform-wide. That count is popularity across the platform, not whether your Mind has the item equipped — use minds mind skills list / minds mind apps list for the per-Mind equipped set. Search skills and apps together:

minds bazaar search "workflow automation" --max 20
minds bazaar search "slack" --tier verified --provider composio --sort equipped

minds bazaar search does not return top-level items. Expect:

{
  "ok": true,
  "query": "slack",
  "max": 20,
  "skills": { "totalCount": 0, "scanned": 0, "returned": 0, "truncated": false, "items": [] },
  "apps": { "totalCount": 0, "scanned": 0, "returned": 0, "truncated": false, "items": [] }
}

Browse skills or apps separately, use --search and --max when you need more than the first catalog slice:

minds bazaar skills list --search "research" --max 10
minds bazaar skills list
minds bazaar skills show skill_abc123
 
minds bazaar apps list --search "notion" --tier verified --max 10
minds bazaar apps show app_xyz789 | jq '.item.tools'

With --search, skills list and apps list return { ok: true, query, totalCount, scanned, returned, truncated, max, sortedBy?, items }. Browse without --search returns the same shape minus query, max, and sortedBy (first slice only; truncated: true when the catalog is larger). Field names for jq: skills use skillId and name; apps use appId and appName (not name). Tools on an app use toolSlug. Example - extract IDs from search:

minds bazaar search "game" --max 5 | jq '{
  skills: [.skills.items[] | {skillId, name}],
  apps: [.apps.items[] | {appId, appName}]
}'

--max defaults to 50, caps at 200; --search auto-scans up to 200 internally. --sort is client-side on the scanned set: equipped sorts by equippedCount descending (platform popularity), name alphabetically, newest by createdAt. --provider on apps filters client-side on the scanned set without --search it only filters the first catalog slice (stderr warns). Truncation warnings go to stderr (warn:); JSON stays on stdout.

Equip skills and apps

After you have a skillId or appId from Bazaar (or elsewhere), list, equip, or unequip on a Mind. Pass --mind with the Mind UUID and --id (repeatable) with the skill or app UUID:

MIND_ID=$(minds list | jq -r '.items[0].mindId')
SKILL_ID=$(minds bazaar skills list --search "research" --max 1 | jq -r '.items[0].skillId')
APP_ID=$(minds bazaar apps list --search "notion" --max 1 | jq -r '.items[0].appId')
 
minds mind skills list --mind "$MIND_ID"
minds mind skills equip --mind "$MIND_ID" --id "$SKILL_ID"
minds mind skills unequip --mind "$MIND_ID" --id "$SKILL_ID"
 
minds mind apps list --mind "$MIND_ID"
minds mind apps equip --mind "$MIND_ID" --id "$APP_ID"
minds mind apps unequip --mind "$MIND_ID" --id "$APP_ID"

Equip and unequip take one or more --id values and return { ok: true, mindId, result: { results: [...] } }. List returns the currently equipped set for that Mind. Equipped skills include source: mind for catalog / Mind-authored skills, system for platform skills (e.g. Skill Architect).

Message Sending and History

With account setup and catalog browsing covered, bind a stable alias to a Mind and send messages. Use a mindId from minds list when you create a conversation. You can pipe the first Mind straight into chat create:

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

Or pass a specific mindId explicitly:

minds chat create --mind {mind-id} --alias main

chat create is idempotent, re-running with the same alias returns the existing conversation instead of failing. Default --wait timeout is 120000 ms; 180000 gives more headroom. If --wait times out, run minds history main — the reply may still have arrived server-side. minds history returns the full human + Mind transcript. Rows use senderType (1 = human, 0 = Mind). History is oldest-first; paginate with --limit (1–200, default 50) and --cursor (a message fingerprint from the previous page — exclusive):

minds history main
minds history main --limit 10
 
# Next page: pass the last fingerprint from the previous response
minds history main --limit 10 --cursor "$(minds history main --limit 10 | jq -r '.items[-1].fingerprint')"

Attachments

Pass a JSON array of attachment objects with --attachments. Prefer a public HTTPS URL for images and files, the Mind fetches the URL server-side. Image: save as attach-url-png.json:

[
  {
    "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
    "fileName": "transparency-demo.png",
    "mimeType": "image/png"
  }
]

minds send main "Describe this image in one sentence." --attachments ./attach-url-png.json --wait --timeout 180000

PDF: save as attach-url-pdf.json:

[
  {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "fileName": "dummy.pdf",
    "mimeType": "application/pdf",
    "extension": "pdf"
  }
]

minds send main "Summarize this PDF in one sentence." --attachments ./attach-url-pdf.json --wait --timeout 180000

Coding agents with local files can base64-encode into a content field instead of url - see the API reference for the full outbound shape. Mind replies may include inbound artifacts on minds history rows:

{
  "artifactId": "7388b65d-144a-49ff-a4dc-cb7c23ded982",
  "slug": "whale_watchtower_skill_artifact_1_0_5",
  "logicalType": "document",
  "mimeType": "application/pdf",
  "extension": "pdf",
  "artifact": "JVBERi0xLjQK..."
}

Use artifact for the base64 file body when present (truncated in this example).

When your Minds are configured and you are ready to embed them in your application, continue with the Minds Client Library .