# Minds CLI

> Install the Minds CLI, verify your API key, and send your first message from the terminal.

Install the CLI after account setup, verify connectivity, then send your first message to a Mind directly from your terminal.

If you work with a coding agent that has terminal access (Cursor, Claude Code or Codex), point it at the Minds CLI, it can install the tool, use your `MINDS_BUILDER_API_KEY`, and send messages for you. You can also run it yourself for quick tests and scripts; either way, it's the fastest way to confirm your account and Minds before you write application code.

Complete [Account setup](/docs/get-started/account-setup) first — create a Mind, issue a Builder API key from the console, then make the key available to the CLI as `MINDS_BUILDER_API_KEY`.

## 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 and CI

For coding agents, sandboxes, or one-off runs, 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"
```

## Verify and explore

```bash
minds doctor --pretty
minds --help
minds chat --help
```

Every subcommand includes copy-paste **Examples** in its `--help` output.

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[] | '
```

## Send your first message

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.

## 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 you are ready to embed Minds in your own app or automation, continue with the [Minds Client Library](/docs/get-started/client-library).