Minds
문서화

시작하기

Minds CLI

Builder Tools를 가장 빠르게 활용하는 방법은 셸 액세스 권한이 있는 코딩 에이전트를 사용하는 것입니다. 한 번 설치하고 API 키를 설정한 다음, 에이전트에게 minds 명령을 대신 실행하도록 요청하세요.

Minds CLI는 Builder API 에 대한 JSON 우선 터미널 인터페이스입니다. 모든 명령은 stdout에 하나의 객체를 출력합니다. 모든 하위 명령은 --help에 복사하여 붙여넣을 수 있는 예제를 제공합니다. 이는 의도적인 것입니다. Cursor, Claude Code, Codex 또는 터미널이 있는 모든 에이전트는 편집기에 머무르는 동안 명령을 검색하고, 실행하고, jq를 통해 파이프하고 자연어로 결과를 보고할 수 있습니다.한 번 설치하고 MINDS_BUILDER_API_KEY를 설정한 다음 에이전트에게 요청하세요. 예를 들면:
  • "내 Mind 목록을 보여주고 첫 번째 Mind의 전체 세부 정보를 표시해"
  • "지난주에 내 Mind가 사용한 Cognition 사용량은 얼마야?"
  • "어제 가장 많은 Cognition을 소비한 도구는 뭐야?"
  • "Bazaar에서 노션 앱을 검색하고 각 앱이 어떤 도구를 제공하는지 보여줘"
  • "내 Mind의 Circle에 colleague@company.com을 추가해"
이러한 프롬프트 뒤에서 에이전트는 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 표준 출력은 요약, 게이트 통제 또는 슬랙 알림을 위해 jq로 깔끔하게 파이프 처리할 수 있습니다. 예 - 첫 번째 Mind의 주간 Cognition 사용량(매주 월요일 09: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 출력에 복사하여 붙여넣을 수 있는 예제가 포함되어 있습니다. 다중 세그먼트 명령의 경우 표준 패턴은 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만 보냅니다. 기본 stdout은 단일 JSON 객체 { ok: true, … }입니다. 진단은 stderr로 이동합니다. minds events는 예외이며 NDJSON 형태로 출력합니다. minds doctor가 키 누락을 보고하면 계정 설정 으로 돌아가서 키를 생성한 다음 export MINDS_BUILDER_API_KEY=…를 실행합니다(또는 프로젝트의 .env에 추가).

내 Mind 목록 보기

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는 요약 필드를 반환합니다. 전체 세부 정보(이메일, 지갑 주소, 체인, 종, 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 사용량 및 남은 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와 상호작용할 수 있는 인간 협력자의 집합입니다. 한 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 간의 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는 스킬과 앱의 공개 카탈로그입니다. Bazaar 명령에는 Builder API 키가 필요하지 않으며, MINDS_BUILDER_API_KEY가 설정되지 않은 CI 및 샌드박스에서 작동합니다. 클라이언트 라이브러리 의 client.bazaar.*에서도 동일한 카탈로그를 사용할 수 있습니다. ID 검색(skillId, appId)을 위해 Bazaar를 사용한 다음, minds mind skills|apps(아래 참조)로 해당 ID를 Mind에 장착하세요. 목록 항목에는 플랫폼 전체에서 해당 스킬 또는 앱을 장착한 Mind의 수를 나타내는 equippedCount가 포함될 수 있습니다. 이 수치는 플랫폼 전체의 인기이며 사용자의 Mind에 항목이 장착되어 있는지 여부는 아닙니다. Mind별 장착된 세트는 minds mind skills list / minds mind apps list를 사용하세요. 스킬과 앱 함께 검색: 
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": [] }
}
스킬이나 앱을 개별적으로 탐색하세요. 첫 번째 카탈로그 슬라이스보다 더 많이 필요할 때는 --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에서 사용할 필드 이름: 스킬은 skillId와 name을 사용하고, 앱은 appId와 appName(name 아님)을 사용합니다. 앱의 도구는 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 기준으로 정렬합니다. 앱의 --provider는 스캔된 집합에 대해 클라이언트 측에서 필터링하며, --search가 없으면 첫 번째 카탈로그 슬라이스만 필터링합니다(stderr에 경고 표시). 잘림 경고는 stderr(warn:)로 출력되고 JSON은 stdout에 유지됩니다.

스킬과 앱 장착

Bazaar(또는 다른 곳)에서 skillId 또는 appId를 얻은 후 Mind에서 나열, 장착 또는 장착 해제할 수 있습니다. --mind에 Mind UUID를, --id(반복 가능)에 스킬 또는 앱 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)는 하나 이상의 --id 값을 받고 { ok: true, mindId, result: { results: [...] } }를 반환합니다. list는 해당 Mind에 현재 장착된 세트를 반환합니다. 장착된 스킬에는 source가 포함됩니다: mind는 카탈로그 또는 Mind가 작성한 스킬, system은 플랫폼 스킬(예: 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는 멱등성을 가지며 동일한 별칭으로 다시 실행하면 실패하는 대신 기존 대화를 반환합니다. 기본 --wait 시간 초과는 120000ms입니다. 180000을 사용하면 더 많은 여유 공간이 생깁니다. --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 행에 인바운드 아티팩트가 포함될 수 있습니다: 
{
  "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를 사용합니다(이 예에서는 잘림).

다음

Mind가 구성되고 애플리케이션에 포함할 준비가 되면 Minds 클라이언트 라이브러리 를 계속 진행하세요.
이 페이지에서