# Minds CLI

> Install the Minds CLI and drive it from Cursor, Claude Code, or any coding agent, JSON stdout and examples in --help so your agent can list Minds, check cognition, and manage your account without you memorizing commands.

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](/docs/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  --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](/docs/get-started/account-setup) first (Mind + Builder API key), then install below or hand the same commands to your agent.

## Install

Requires **Node 22+**.

```bash
npm install -g @animocabrands/minds-cli
```

Update after a new release:

```bash
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:

```bash
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:

```bash
export MINDS_BUILDER_API_KEY=your_key_here
minds doctor --pretty
```

```bash
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:

```bash
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):

```yaml
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: ${}
        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:

```bash
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   --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 ``; diagnostics go to stderr. `minds events` is the exception, it prints NDJSON lines.

If `minds doctor` reports a missing key, return to [Account setup](/docs/get-started/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:

```bash
minds list --pretty
```

Pipe to jq when scripting:

```bash
minds list | jq '.items[] | '
```

## 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`):

```bash
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`.

```bash
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`:

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

## Enable and disable a Mind

Pause or resume a Mind as needed:

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

Power down a Mind when its cognition balance is exhausted:

```bash
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:

```bash
minds circle show --mind "$MIND_ID"
minds circle list | jq '.items[] | '
```

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

```bash
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 ``; `add` and `remove` return `{ ok: true, mindId, result:  }` 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](/docs/get-started/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:

```bash
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:

```json
{
  "ok": true,
  "query": "slack",
  "max": 20,
  "skills": ,
  "apps":
}
```

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

```bash
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 ``. 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:

```bash
minds bazaar search "game" --max 5 | jq '{
  skills: [.skills.items[] | ],
  apps: [.apps.items[] | ]
}'
```

`--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:

```bash
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:  }`. 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`:

```bash
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:

```bash
minds chat create --mind  --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):

```bash
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`:

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

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

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

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

```bash
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](/docs/api) for the full outbound shape. Mind replies may include **inbound** artifacts on `minds history` rows:

```json
{
  "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).

## Next

When your Minds are configured and you are ready to embed them in your application, continue with the [Minds Client Library](/docs/get-started/client-library).