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 等）を使う場合のコマンド。

第1引数が登録済みツール名または `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` セクション」の2つ。`shared` はツールのクレデンシャル解決（`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 のクレデンシャルを巻き込まないため）。単回使用トークンのように「有効な複製が同時に1つしか存在し得ない」値は、保管先を1箇所に決めて分散させない。

**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` へ反映される。