Minds
ドキュメンテーション

はじめに

Minds CLI

Builder Toolsを最速で使いこなすには、シェルにアクセスできるコーディングエージェントの活用がおすすめです。一度インストールしてAPIキーを設定すれば、あとは `minds` コマンドの実行を指示するだけです。

Minds CLIは、Builder API へのJSON優先のターミナルインターフェースです。すべてのコマンドは標準出力にオブジェクトを1つ出力し、すべてのサブコマンドには --help 出力にコピペ可能なサンプルが含まれています。これは意図的な設計です。Cursor・Claude Code・Codex、あるいはターミナルを扱えるどのエージェントでも、エディタから離れることなくコマンドを見つけて実行し、 jq でパイプ処理し、平易な言葉で結果を報告できます。インストールし、 MINDS_BUILDER_API_KEY を設定したら、エージェントに尋ねてください 例えば：
  • 「私のMindsを一覧表示して、一番最初のMindの詳細を見せて」
  • 「過去1週間でMindはどのくらいのCognitionを使用した？」
  • 「昨日最もCognitionを消費したツールはどれ？」
  • 「BazaarでNotionアプリを検索し、それぞれが公開しているツールを表示して」
  • 「 colleague@company.com を私のMindのサークルに追加して」
これらのプロンプトの裏側で、エージェントは 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 などを実行しています。フラグを覚える必要はなく、 minds <command> --help がエージェントの読み取れる信頼できる情報源です。診断メッセージや省略のヒントはstderrに出力され、stdoutはスクリプトやCI向けにクリーンなJSONのまま保たれます。まずアカウント設定 （Mind + Builder APIキー）を完了してから、以下の手順でインストールするか、同じコマンドをエージェントに渡してください。

インストール

Node 22+ が必要です。 
npm install -g @animocabrands/minds-cli
最新バージョンへの更新： 
npm install -g @animocabrands/minds-cli@latest

エージェント、サンドボックス、CI

コーディングエージェントも、以下と同じインストール手順を使用できます。サンドボックス・一時環境・CIの場合は、グローバルインストールを省略してください： 
npx @animocabrands/minds-cli@latest doctor --pretty
npx @animocabrands/minds-cli@latest list
CLIはシェル環境から MINDS_BUILDER_API_KEY を読み取ります。以下のいずれかを使用できます： 
export MINDS_BUILDER_API_KEY=your_key_here
minds doctor --pretty
MINDS_BUILDER_API_KEY=your_key_here minds doctor --pretty
プロジェクトディレクトリ内の .env ファイルも利用できます。シェルに変数が未設定の場合、CLIが自動的にこれを読み込みます。スクリプト実行時は --builder-api-key を渡してください： 
npx @animocabrands/minds-cli@latest chat list --builder-api-key "$MINDS_BUILDER_API_KEY"

GitHub Actions

CIでもローカルと同じ方法でCLIを使用できます： npx 、Node 22+、そしてリポジトリシークレットとしての MINDS_BUILDER_API_KEY です。JSON形式のstdoutは jq にそのままパイプでき、サマリー作成・ゲート判定・Slack通知などに使えます。 例：最初のMindの週次Cognition使用量（毎週月曜9:00 UTCに実行、手動トリガーも可能）： 
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'

検証と探索

簡単な健全性チェックのためにこれらを自分で実行するか、インストール後にエージェントに実行を依頼してください： 
minds doctor --pretty
minds --help
minds chat --help
minds usage by-tool --help
すべてのサブコマンドには、 --help 出力にコピペ可能な 例（Examples） が含まれています。マルチセグメントコマンドの場合、標準的なパターンは minds <group> <subcmd> --help （たとえば minds usage by-tool --help ）です。これらも機能します： minds help usage by-tool および minds usage --help by-tool 。 認証されたリクエストには、Builder APIキーを含む X-Api-Key が必要です。 X-Access-Key は非推奨であり、HTTPリクエストには使用しないでください。CLIは MINDS_BUILDER_API_KEY （または --builder-api-key 、非推奨のCLIフラグ --access-key ）を読み取り、 X-Api-Key のみ を送信します。 デフォルトの標準出力は1つのJSONオブジェクト { ok: true, … } です。診断はstderrに送られます。 minds events は例外であり、NDJSONの行を出力します。 minds doctor がキーの欠落を報告した場合は、アカウント設定 に戻ってキーを作成し、 export MINDS_BUILDER_API_KEY=… を実行します（またはプロジェクトの .env に追加します）。

Mindsの一覧表示

minds list は、アカウントの各Mindに対してBuilder APIを呼び出し、 mindId 、 name 、 model 、 species 、および関連フィールドを表示します。コンソールからIDをコピーする必要はありません。 minds doctor が成功した後： 
minds list --pretty
スクリプトでjqにパイプする： 
minds list | jq '.items[] | {mindId, name}'

Mindの詳細

minds list はサマリー情報を返します。メールアドレス・ウォレットアドレス・チェーン・species・ isEnabled などの完全な詳細情報には minds mind show を使用してください。 $MIND_ID には、 minds list が返すMindのUUIDを設定します（表示名の 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'
レスポンス： { ok: true, mind: { … } } 。

Cognition残高と使用量

Mindは、メッセージを受信したときだけでなく、推論・ツール実行・自律的なタスク遂行の際にもCognitionを消費します。各MindのCognition使用量と残りの残高を確認するには、 minds list から取得した mindId を渡してください。 
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 は時間経過に伴うCognition使用量を報告します。 usage by-tool はツールごとの使用量をサマリーとタイムラインで内訳表示します。受け付けられる間隔はコマンドによって異なります： usage show は 1m ・ 5m ・ 15m ・ 1h ・ 1d ・ 1w ・ 1M を、 usage by-tool は hour ・ day ・ week ・ month のみを受け付けます。CLIはAPI呼び出し前に間隔を検証するため、無効な値を指定すると終了コード2で終了し、有効な値の一覧がヒントとして表示されます。 Cognition は、Mindの推論・ツール利用・自律的な作業を支えます。残りの Cognition残高 は cognition balance で確認できます： 
minds cognition balance --mind "$MIND_ID" | jq '.balance.cognition'

Mindの有効化と無効化

必要に応じてMindを一時停止・再開できます： 
minds mind disable --mind "$MIND_ID"
minds mind enable --mind "$MIND_ID"
Cognition残高が尽きたときは、Mindを停止できます： 
minds cognition balance --mind "$MIND_ID" | jq -e '.balance.cognition <= 0' && minds mind disable --mind "$MIND_ID"

Circles

Mindの Circle は、そのMindとやり取りできる人間の協力者の集合です。1つのMind単位、またはアカウント上のすべてのMindを横断して、メンバー一覧を取得できます： 
minds circle show --mind "$MIND_ID"
minds circle list | jq '.items[] | {mindId, memberCount: (.members | length)}'
メールでコラボレーターを追加または削除します。 --email は繰り返し可能です： 
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
Circleは 人間コラボレーターのメール のみを受け入れます。MindとMindのCircleメンバーシップはサポートされていません。 circle add はデフォルトで新しいメンバーをアクティブにします。コマンドを実行せずに削除されるメールをプレビューするには、 remove で --dry-run を渡します。 レスポンスの形状はコマンドによって異なります： circle show は { ok: true, mindId, items: CircleMember[] } を返します。 add と remove は、メールごとの結果を含む { ok: true, mindId, result: { items, summary } } を返します。 circle add で重複するメールを指定すると、 action: "exists" または "already_in_circle" が返される場合があります。CLIはこれらを成功として扱い、変更が実質的な効果を持たなかった場合にのみstderrで警告します。

Bazaarカタログ

Bazaarは、SkillとAppの公開カタログです。Bazaarコマンドは Builder APIキーを必要としません 。 MINDS_BUILDER_API_KEY が設定されていなくても、CIやサンドボックスで機能します。同じカタログは、 クライアントライブラリ で client.bazaar.* として利用できます。 IDの発見 （ skillId 、 appId ）にBazaarを使用し、その後 minds mind skills|apps （下記参照）でMindにそれらのIDを装備してください。 リスト項目には、 プラットフォーム全体で そのSkillまたはAppを装備しているMindの数を示す equippedCount が含まれる場合があります。この数はプラットフォーム全体での人気であり、 あなたの Mindがそのアイテムを装備しているかどうかを示すものではありません。Mindごとの装備セットには minds mind skills list / minds mind apps list を使用してください。 SkillとAppを一緒に検索する： 
minds bazaar search "workflow automation" --max 20
minds bazaar search "slack" --tier verified --provider composio --sort equipped
minds bazaar search はトップレベルの items を 返しません 。期待される結果： 
{
  "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": [] }
}
SkillやAppを個別に閲覧する場合、カタログの最初のスライス以上が必要なときは、 --search と --max を使用します： 
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'
--search を使用すると、 skills list と apps list は { ok: true, query, totalCount, scanned, returned, truncated, max, sortedBy?, items } を返します。 --search なしで閲覧すると、 query 、 max 、 sortedBy を除いた同じ形状が返されます（最初のスライスのみ。カタログが大きい場合は truncated: true ）。 jq用のフィールド名：Skillは skillId と name 、Appは appId と appName （ name ではありません）、App上のToolは toolSlug を使用します。例：検索結果からIDを抽出する： 
minds bazaar search "game" --max 5 | jq '{
  skills: [.skills.items[] | {skillId, name}],
  apps: [.apps.items[] | {appId, appName}]
}'
--max はデフォルト50、上限200です。 --search は内部で最大200件まで自動スキャンします。 --sort はスキャン済みの範囲内でクライアント側で処理されます： equipped は equippedCount の降順（プラットフォーム全体の人気順）、 name はアルファベット順、 newest は createdAt 順でソートします。Appの --provider は、 --search なしの場合は最初のカタログの一部のみをフィルタリングします（stderrに警告が表示されます）。省略の警告はstderrに（ warn: ）、JSONはstdoutにそのまま出力されます。

SkillとAppの装備

Bazaar（またはその他）から skillId や appId を取得したら、Mindに対して一覧表示・装備・装備解除ができます。 --mind にMindのUUID、 --id （繰り返し可能）にSkillまたは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）と装備解除（unequip）は1つ以上の --id 値を受け取り、 { ok: true, mindId, result: { results: [...] } } を返します。listはそのMindで現在装備されているセットを返します。 装備済みのSkillには source が含まれます： mind はカタログまたはMindが作成したSkill、 system はプラットフォーム提供のSkill（例：Skill Architect）を表します。

メッセージ送信と履歴

アカウント設定とカタログ閲覧が済んだら、安定した alias（エイリアス） をMindに紐づけてメッセージを送信します。会話を作成する際は minds list が返す mindId を使用してください。最初のMindをそのまま chat create にパイプすることもできます： 
minds chat create --mind "$(minds list | jq -r '.items[0].mindId')" --alias main
minds send main "Hello" --wait --timeout 180000
または、特定の mindId を明示的に渡します： 
minds chat create --mind {mind-id} --alias main
chat create は べき等 です。同じaliasで再実行しても失敗せず、既存の会話がそのまま返されます。 --wait のデフォルトタイムアウトは120,000ミリ秒です。180,000に設定するとより余裕を持てます。 --wait がタイムアウトした場合は minds history main を実行してください。返信がサーバー側にはすでに届いている可能性があります。 minds history は、人間とMindの完全な会話履歴を返します。行には senderType （ 1 = 人間、 0 = Mind）が含まれます。履歴は古い順で、 --limit （1〜200、デフォルト50）と --cursor （前ページの最後のメッセージの fingerprint 、排他的）でページングします： 
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 には、添付オブジェクトのJSON 配列 を渡します。画像やファイルには、公開された HTTPS URL の使用を推奨します。Mindがサーバー側でそのURLを取得します。 画像： 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： 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
ローカルファイルを扱うコーディングエージェントは、 url の代わりに content フィールドへbase64エンコードして渡せます。送信データの完全な形式は APIリファレンス を参照してください。Mindからの返信には、 minds history の行に 受信側 のartifactが含まれることがあります： 
{
  "artifactId": "7388b65d-144a-49ff-a4dc-cb7c23ded982",
  "slug": "whale_watchtower_skill_artifact_1_0_5",
  "logicalType": "document",
  "mimeType": "application/pdf",
  "extension": "pdf",
  "artifact": "JVBERi0xLjQK..."
}
存在する場合は、base64ファイルの本文に artifact を使用します（この例では切り捨てられています）。

ネクストステップ

Mindsの設定が完了し、アプリケーションへの組み込み準備が整ったら、次は Mindsクライアントライブラリ へ進みましょう。
このページで