Animaworks Guide

---
name: animaworks-guide
description: >-
  animaworks 명령어의 완전한 참조. 서버 조작·Anima 관리·모델·작업·설정·RAG·자산·외부 도구의 CLI 형식을 정리한다.
  Use when: 서브커맨드 형식 확인, 서버 시작 종료, Anima 생성·모델 변경·작업 추가·로그·설정·인덱스 조작이 필요할 때.
---


# AnimaWorks CLI 완전 참조

AnimaWorks의 모든 조작은 `animaworks` 명령어로 수행한다.
이 스킬은 모든 서브커맨드의 형식·인자·구체적인 예를 정리한 참조다.

운영의 개념이나 규칙은 `common_knowledge/` 및 `reference/`를 참조:
- 메시징 규칙 → `communication/messaging-guide.md`
- 작업 관리 → `operations/task-management.md`
- 도구 체계 → `operations/tool-usage-overview.md`
- 조직 구조 → `reference/organization/structure.md`
- 모델 선택·설정 → `reference/operations/model-guide.md`

---

## 비권장·호환 별칭

```bash
# --local（deprecated: ProcessSupervisor をバイパスする直接実行。HTTP API 経由が推奨）
animaworks chat {名前} "..." --local
animaworks heartbeat {名前} --local
```

권장: `animaworks start`(또는 `serve`)로 서버를 시작하고, `--local`를 붙이지 않고 `chat` / `heartbeat`를 사용한다.

`gateway` / `worker` 서브커맨드는 숨겨진 호환용(분산 아키텍처 폐지 후에는 사용하지 않음).

---

## 서버 조작(기본적으로 사용하지 않을 것)

```bash
animaworks start                         # サーバー起動（デフォルト: 0.0.0.0:18500）
animaworks serve                         # start のエイリアス
animaworks start --host 127.0.0.1        # バインドアドレス指定
animaworks start --port 8080             # ポート指定
animaworks start --foreground            # フォアグラウンド起動（-f、デバッグ用）
animaworks stop                          # サーバー停止
animaworks stop --force                  # 強制停止（SIGTERM後SIGKILL、孤立プロセスも終了）
animaworks restart                       # サーバー再起動（--host / --port / -f / --force 可）
animaworks restart --force               # 強制停止してから再起動
animaworks status                        # システム状態確認（プロセス・Anima一覧）
animaworks reset                         # ランタイムディレクトリ削除＋再初期化
animaworks reset --restart               # リセット後サーバー自動起動
```

---

## Anima 관리(anima 서브커맨드)

### 목록·상태·상세 정보

```bash
animaworks anima list                    # 全Anima一覧（名前・有効/無効・モデル・supervisor）
animaworks anima list --local            # API不使用・ファイルシステム直接スキャン
animaworks anima status                  # 全Animaのプロセス状態（State・モデル・PID・Uptime）
animaworks anima status {名前}           # 特定Animaのプロセス状態
animaworks anima info {名前}             # 設定詳細（モデル・ロール・credential・voice等）
animaworks anima info {名前} --json      # JSON出力
animaworks anima permissions {名前}      # ツール許可を表示（load_permissions: JSON 優先、レガシーは permissions.md）
```

`anima info`의 출력 항목:
- Anima 이름, Enabled, Role, Model, Execution Mode(내장 라벨은 S/C/D/G/X/A）
- Credential, Fallback Model, Context Threshold, Max Tokens, Thinking / Thinking Effort, Supervisor, Mode S Auth
- Voice 설정(tts_provider, voice_id, speed, pitch 등, status.json의 voice 사전을 열거)

### 생성

```bash
# キャラクターシート（MD）から作成（推奨）
animaworks anima create --from-md {ファイル} [--role {role}] [--name {名前}]

# テンプレートから作成
animaworks anima create --template {テンプレート名} [--name {名前}]

# ブランク作成
animaworks anima create --name {名前}
```

### 활성화·비활성화·삭제

```bash
animaworks anima enable {名前}           # 有効化（休養から復帰）
animaworks anima disable {名前}          # 無効化（休養）
animaworks anima delete {名前}           # 削除（ZIPアーカイブ後）
animaworks anima delete {名前} --no-archive  # アーカイブなしで削除
animaworks anima delete {名前} --force   # 確認なしで削除
animaworks anima restart {名前}          # プロセス再起動
```

### 활동 감사(audit)

대상 Anima의 `activity_log`을 읽는다(도움말 문구는 subordinate지만, 이름을 지정하면 임의의 Anima로 가능).

```bash
animaworks anima audit {名前}            # 活動監査（デフォルト: report モード・直近1日）
animaworks anima audit {名前} --days 7   # 集計日数（最大30）
animaworks anima audit --all             # 全Animaを対象（タイムラインをマージ）
animaworks anima audit {名前} --since 09:00   # 当日 JST の時刻以降（指定時は --days より優先）
animaworks anima audit {名前} --mode summary  # 統計サマリー（省略時は report＝時系列）
```

### 모델 변경

```bash
animaworks anima set-model {名前} {モデル名}
animaworks anima set-model {名前} {モデル名} --credential {credential名}
animaworks anima set-model --all {モデル名}   # 全Anima一括変更
```

변경 후 서버가 실행 중이면 `anima restart {名前}`이 필요하다.

### 백그라운드 모델(Heartbeat/Cron용)

```bash
animaworks anima set-background-model {名前} {モデル名}   # Heartbeat・Cron用モデルを設定
animaworks anima set-background-model {名前} {モデル名} --credential {credential名}
animaworks anima set-background-model {名前} --clear    # オーバーライド解除（メインモデルにフォールバック）
animaworks anima set-background-model --all --clear     # 有効な全Animaの background を一括クリア
animaworks anima set-background-model --all {モデル名}   # 有効な全Anima一括（モデルは位置引数でも可: `{モデル} --all`）
```

### 이름 변경

```bash
animaworks anima rename {旧名前} {新名前}
animaworks anima rename {旧名前} {新名前} --force   # 確認なしで実行
```

### 역할 변경

```bash
# ロール変更（テンプレート再適用 + 自動restart）
animaworks anima set-role {名前} {role}

# status.jsonのroleフィールドのみ変更（テンプレートは触らない）
animaworks anima set-role {名前} {role} --status-only

# ファイル更新のみ・再起動しない
animaworks anima set-role {名前} {role} --no-restart
```

set-role로 자동 업데이트되는 파일(`--status-only` 외):
- `status.json` — role 및 역할 `defaults.json` 유래의 model / context_threshold / conversation_history_threshold 등을 병합
- `specialty_prompt.md` — 역할 템플릿에서 덮어쓰기
- `permissions.json` — 역할 템플릿에서 덮어쓰기(기존의 `permissions.md`은 읽기 시 JSON으로 이관될 수 있음)

유효한 역할: `engineer`, `researcher`, `manager`, `writer`, `ops`, `general`

### 핫 리로드

```bash
animaworks anima reload {名前}           # status.json からモデル設定を再読み込み（プロセス再起動なし）
animaworks anima reload --all            # 全Animaをリロード
```

---

## 모델 정보(models 서브커맨드)

```bash
animaworks models                        # サブコマンド一覧（help）
animaworks models list                   # 組み込みカタログ（KNOWN_MODELS）: 名前・モード・コンテキスト・注記
animaworks models list --mode S          # モードでフィルタ（CLI の choices は S / A / B / C のみ・大文字小文字可）
animaworks models list --json            # JSON出力
animaworks models info {モデル名}        # 任意モデル名の解決結果（実行モード・コンテキスト窓・閾値・ソース）
animaworks models show                   # ~/.animaworks/models.json のパターン一覧
animaworks models show --json            # models.json を生JSON出力
```

`models list`에 없는 모델(예: `cursor/*`, `gemini/*`)은 `models info <名前>`와 `models.json`로 확인한다.

상세 → `reference/operations/model-guide.md`

---

## 채팅·메시징

```bash
# Animaとチャット（人間→Anima）
animaworks chat {名前} "メッセージ"
animaworks chat {名前} "メッセージ" --from {送信者名}
animaworks chat {名前} "メッセージ" --local  # deprecated（ヘルプ参照）

# Anima間メッセージ送信
animaworks send {送信者} {受信者} "メッセージ"
animaworks send {送信者} {受信者} "メッセージ" --intent report   # report / delegation / question または省略（空）
animaworks send {送信者} {受信者} "メッセージ" --reply-to {メッセージID}
animaworks send {送信者} {受信者} "メッセージ" --thread-id {スレッドID}

# ハートビート手動起動
animaworks heartbeat {名前}
animaworks heartbeat {名前} --local      # deprecated（ヘルプ参照）
```

---

## Board(공유 채널)

```bash
animaworks board read {チャネル名}                      # チャネル読み取り（デフォルト --limit 20）
animaworks board read {チャネル名} --limit 50           # 最大件数
animaworks board read {チャネル名} --human-only         # 人間の投稿のみ
animaworks board post {送信者} {チャネル名} "テキスト"  # チャネルへ投稿
animaworks board dm-history {自分} {相手}               # DM履歴（デフォルト --limit 20）
animaworks board dm-history {自分} {相手} --limit 50    # 件数指定
```

---

## 설정 관리(config 서브커맨드)

```bash
animaworks config                        # ヘルプ表示（子コマンドまたは -i が無い場合）
animaworks config -i                     # 対話式ウィザード（credential・Anima設定）
animaworks config list                   # 全設定値の一覧表示
animaworks config list --section system  # セクションでフィルタ（例: system, credentials）
animaworks config list --show-secrets    # API keyを表示
animaworks config get {キー}             # 特定の設定値取得（ドット記法: system.mode）
animaworks config get {キー} --show-secrets
animaworks config set {キー} {値}        # 設定値を変更
```

**주의**: Anima의 모델·credential 등은 `status.json`이 SSoT. `animas.{名前}.model` 등의 직접 설정은 비권장. `animaworks anima set-model`을 사용할 것.

---

## 프로필(profile 서브커맨드·멀티테넌트)

여러 AnimaWorks 인스턴스(별도 데이터 디렉터리)를 관리한다.

```bash
animaworks profile list                  # 全プロファイル一覧（data_dir・port・状態）
animaworks profile add {名前}             # プロファイル登録（data_dir: ~/.animaworks/{名前}）
animaworks profile add {名前} --data-dir /path/to/data --port 18510
animaworks profile remove {名前}         # 登録解除（データは残る）
animaworks profile start {名前}          # そのプロファイルのサーバー起動
animaworks profile stop {名前}           # そのプロファイルのサーバー停止
animaworks profile stop {名前} --force   # 強制停止
animaworks profile start-all             # 全プロファイルを起動
animaworks profile stop-all              # 全プロファイルを停止
animaworks profile stop-all --force      # 強制停止で全停止
```

---

## 로그 열람(logs)

```bash
animaworks logs {名前}                   # 特定Animaのログ表示
animaworks logs --all                    # サーバー＋全Animaのログ表示
animaworks logs {名前} --lines 100       # 表示行数指定（デフォルト: 50）
animaworks logs {名前} --date 20260301   # 特定日のログ表示
```

---

## 비용 확인(cost)

```bash
animaworks cost                          # 全Animaのトークン使用量・コスト
animaworks cost {名前}                   # 特定Animaのコスト
animaworks cost --today                  # 本日のみ
animaworks cost --days 7                 # 直近7日（デフォルト: 30日）
animaworks cost --json                   # JSON出力
```

---

## 작업 관리(task 서브커맨드)

**전제**: 실행 전에 `ANIMAWORKS_ANIMA_DIR`을 대상 Anima의 디렉터리(예: `~/.animaworks/animas/{名前}`)에 설정할 것. 미설정이면 오류가 된다(Anima 자식 프로세스 내의 `animaworks-tool task`이나, 셸에서 변수를 부여한 `animaworks task`가 예상 용도).

```bash
animaworks task list                     # タスク一覧（JSON）
animaworks task list --status pending    # ステータスでフィルタ（pending/in_progress/done/cancelled）
animaworks task add --assignee {名前} --instruction "タスク内容"   # 既定 --source anima
animaworks task add --assignee {名前} --instruction "内容" --source human
animaworks task add ... --relay-chain alice,bob   # カンマ区切りリレー鎖（任意）
animaworks task add ... --summary "1行要約"       # 省略時は instruction の先頭100文字
animaworks task update --task-id {ID} --status done
animaworks task update --task-id {ID} --status done --summary "完了サマリー"
```

---

## RAG 인덱스 관리

의존: RAG 스택 미설치 시 `pip install 'animaworks[rag]'`이 필요(CLI가 오류를 표시하고 종료).

```bash
animaworks index                         # 全Anima: knowledge/episodes/procedures/skills + state/conversation.json の要約
                                         # + common_knowledge/common_skills（有効Animaごと）+ shared/users
animaworks index --anima {名前}          # 当該Animaのみ（共有コレクション・shared/users はスキップ）
animaworks index --anima {名前} --shared # 当該Animaのメモリに加え common_knowledge/common_skills も更新
animaworks index --full                  # コレクション削除からの全再構築（埋め込みモデル変更・L2→cosine 移行時は必須）
animaworks index --dry-run               # 確認のみ
```

- **conversation_summary**: `state/conversation.json`의 `compressed_summary`을 인덱스 대상에 포함(해당 파일이 있는 경우).
- **L2 거리의 기존 컬렉션**: 서버 비가동으로 로컬 Chroma에 직접 접근하는 경우, `--full` 없이는 cosine 이행 경고가 나올 수 있음(메시지에 따라 `--full`를 실행).
- **서버 실행 중**: `server.pid` 감지 시, CLI는 `ANIMAWORKS_VECTOR_URL` / `ANIMAWORKS_EMBED_URL`을 설정하여 HTTP 경유로 인덱스·임베딩을 수행하고, Chroma의 동시 접근 경합을 피한다.
- **임베딩 모델**: `index_meta.json`의 기록과 설정이 다른 경우, `--full` 없이는 오류로 종료한다.

---

## 런타임 이행(migrate)

```bash
animaworks migrate                       # 未適用のマイグレーションを実行
animaworks migrate --dry-run             # 変更プレビュー
animaworks migrate --verbose             # ファイル単位の詳細
animaworks migrate --list                # ステップ一覧と適用済みフラグ
animaworks migrate --force               # 状態に関わらず再適用
```

실행 중인 서버가 있으면 경고가 나온다. `~/.animaworks/config.json`이 없으면 실패한다.

---

## 자산 조작

### 자산 최적화

```bash
animaworks optimize-assets                              # assets/ を持つ全Anima（anim_*.glb ストリップ、avatar_chibi*.glb に Draco は既定で実行）
animaworks optimize-assets --anima {名前}               # 特定Animaのみ（短縮形: -a {名前}）
animaworks optimize-assets --dry-run                    # 確認のみ
animaworks optimize-assets --all                        # 簡素化・テクスチャ処理・Draco 等をまとめて適用
animaworks optimize-assets --simplify                   # メッシュ簡素化（既定比率 0.27 前後）
animaworks optimize-assets --simplify 0.2              # 簡素化比率を数値で指定
animaworks optimize-assets --texture-compress           # WebP 化（--texture-resize 省略時は 1024 相当の扱い）
animaworks optimize-assets --texture-resize 512         # テクスチャ最大辺
animaworks optimize-assets --skip-backup                # 実行前バックアップをスキップ
```

### 자산 재생성(Vibe Transfer)

```bash
animaworks remake-assets {名前} --style-from {参照Anima}   # 参照の fullbody を基準にスタイル転写
# --steps: カンマ区切り。既定は全ステップ。候補:
#   fullbody, bustup, icon, chibi, 3d, rigging, animations
animaworks remake-assets {名前} --style-from {参照} --steps fullbody,icon
animaworks remake-assets {名前} --style-from {参照} --prompt "..."   # prompt.txt の上書き
animaworks remake-assets {名前} --style-from {参照} --vibe-strength 0.6
animaworks remake-assets {名前} --style-from {参照} --vibe-info-extracted 0.8
animaworks remake-assets {名前} --style-from {参照} --seed 42          # fullbody の再現性
animaworks remake-assets {名前} --style-from {参照} --image-style anime|realistic
animaworks remake-assets {名前} --style-from {参照} --dry-run
animaworks remake-assets {名前} --style-from {参照} --no-backup
```

---

## 외부 도구 실행(animaworks-tool)

Anima가 외부 서비스(Slack, Gmail, GitHub 등)를 사용하는 경우의 명령어.

첫 번째 인자가 등록된 도구 이름 또는 `submit`일 때, `animaworks`는 내부에서 `animaworks-tool`로 대체된다(예: `animaworks web_search query "..."`).

```bash
# ヘルプ表示
animaworks-tool {ツール名} --help

# 実行
animaworks-tool {ツール名} {サブコマンド} [引数...]

# バックグラウンド実行（長時間ツール向け）
animaworks-tool submit {ツール名} {サブコマンド} [引数...]
```

### 구체적인 예

```bash
animaworks-tool web_search query "AnimaWorks framework"
animaworks-tool slack send "#general" "おはようございます"   # gated: 明示的な許可が必要
animaworks-tool github issues --repo owner/repo
animaworks-tool submit image_gen pipeline "1girl, ..." --anima-dir $ANIMAWORKS_ANIMA_DIR
```

submit의 상세 → `common_knowledge/operations/background-tasks.md`

**디렉터리 정리**

- **`state/background_tasks/`** — BackgroundTaskManager가 저장하는 실행 결과 JSON(`running` / `completed` / `failed`). `animaworks-tool submit`의 투입 내용과 시도는 TaskStore에 저장하고, `internal list-background-tasks` / `check-background-task`은 이 결과 JSON을 읽는다.
- **`state/background_notifications/`** — 도구 완료 알림 등을 heartbeat가 흡수하는 용도(MCP·스케줄러 등이 쓰는 경로 있음). CLI의 `list-background-tasks`과는 별개.

### 자식 프로세스용 서브커맨드(internal / vault / supervisor)

모두 **`ANIMAWORKS_ANIMA_DIR` 필수**(`task`와 동일). 톱레벨 `animaworks`에도 동일 이름의 서브커맨드가 등록되어 있다.

**internal**

```bash
animaworks-tool internal archive-memory {相対パス}    # knowledge/ episodes/ procedures/ 以下のみ
animaworks-tool internal check-permissions {ツール名} [アクション]
# ※ permissions.json（external_tools の allow/deny と gated action）で判定。判定できないときは不許可として返る
animaworks-tool internal create-skill {名前} [--content ...]   # 省略時は標準入力
animaworks-tool internal manage-channel create|archive {チャネル名}
animaworks-tool internal list-background-tasks
animaworks-tool internal check-background-task {task_id}
```

**vault**(Anima 네임스페이스가 있는 KV)

저장 위치는 「자신의 Anima 네임스페이스」와 「`shared` 섹션」의 두 가지. `shared`은 도구의 credential 해결(`get_credential`)이 읽는 곳으로, `--shared`를 붙여 쓴다. `get` / `list`은 미지정 시 자신의 네임스페이스 → `shared` 순서로 둘 다 본다.

```bash
animaworks-tool vault get {キー}              # 自分の名前空間 → shared の順に探す
animaworks-tool vault get {キー} --shared     # shared のみ
animaworks-tool vault store {キー} {値}       # 自分の名前空間へ
printf '%s' "{値}" | animaworks-tool vault store {キー} --shared   # shared へ（値は stdin 経由のみ）
animaworks-tool vault list                    # {"namespace":..., "keys":[...], "shared":[...]}
animaworks-tool vault list --shared           # shared のみ
animaworks-tool vault delete {キー}           # 自分の名前空間から削除
animaworks-tool vault delete {キー} --shared  # shared から削除
```

`delete`만은 캐스케이드하지 않는다(`--shared` 없이 shared의 credential을 끌어들이지 않기 위해). 단회 사용 토큰처럼 「유효한 복제가 동시에 하나만 존재할 수 있는」 값은 보관 위치를 한 곳으로 정해 분산시키지 않는다.

**supervisor**(`ANIMAWORKS_ANIMA_DIR`의 Anima 이름을 기준으로, status.json의 supervisor 관계로 하위를 해결)

```bash
animaworks-tool supervisor org-dashboard
animaworks-tool supervisor ping [--name {部下名}]    # 省略時は全配下
animaworks-tool supervisor read-state {部下名}      # 位置引数（祖先関係チェックあり）
animaworks-tool supervisor task-tracker [--status delegated]   # 既定 status=delegated（文字列でフィルタ）
```

### 백그라운드 작업 확인

- 대화 중: MCP 도구 `list_background_tasks` / `check_background_task`
- CLI: `animaworks-tool internal list-background-tasks` / `check-background-task {task_id}`(`ANIMAWORKS_ANIMA_DIR` 설정 하, `state/background_tasks/`)

---

## 초기화·마이그레이션

```bash
animaworks init                          # ランタイムディレクトリ初期化（~/.animaworks/）
animaworks init --force                  # 既存にテンプレート差分をマージ
animaworks init --skip-anima             # インフラのみ初期化（Anima作成スキップ）
animaworks init --template {名前}       # テンプレートからAnimaを非対話で作成
animaworks init --from-md {PATH}         # MDファイルからAnimaを非対話で作成
animaworks init --blank {名前}           # ブランクAnimaを非対話で作成
animaworks init --from-md {PATH} --name {名前}  # 作成時の名前を上書き
旧形式の cron.md はサーバ起動時と `animaworks migrate` で自動変換される。
```

스키마 이행은 `animaworks migrate`(위)을 참조.

---

## 글로벌 옵션

```bash
animaworks --gateway-url http://host:port {コマンド}   # API ベース URL（既定: http://localhost:18500）
animaworks --data-dir /path/to/data {コマンド}         # ランタイムディレクトリ（~/.animaworks 相当）
```

`--data-dir`은 서브커맨드 실행 전에 `ANIMAWORKS_DATA_DIR`로 반영된다.