Minds
Documentation

Get Started

Minds CLI

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 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+. 
npm install -g @animocabrands/minds-cli
Update after a new release: 
npm install -g @animocabrands/minds-cli@latest

Agents and CI

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

Verify and explore

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 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}'

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

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).

Next

When you are ready to embed Minds in your own app or automation, continue with the Minds Client Library .
On this page