animaworks-guide

name	animaworks-guide
description	Full animaworks CLI reference: server, Anima lifecycle, models, tasks, config, RAG, assets, external tools. Use when: looking up subcommands, starting or stopping the server, or managing Anima, models, tasks, logs, config, indexes.

AnimaWorks CLI Complete Reference

All AnimaWorks operations are performed via the animaworks command. This skill is a complete reference for all subcommands, arguments, and examples.

For operational concepts and rules, see common_knowledge/:

• Messaging rules → communication/messaging-guide.md
• Task management → operations/task-management.md
• Tool system → operations/tool-usage-overview.md
• Organization structure → reference/organization/structure.md
• Model selection and config → reference/operations/model-guide.md

---

Server Operations (Generally Avoid)

animaworks start                         # Start server (default: 0.0.0.0:18500)
animaworks start --port 8080             # Specify port
animaworks start --foreground            # Foreground mode (for debugging)
animaworks stop                          # Stop server
animaworks restart                       # Restart server
animaworks status                        # Check system state (processes, Anima list)
animaworks reset                         # Delete runtime directory + reinitialize
animaworks reset --restart               # Reset then auto-start server

---

Anima Management (anima subcommand)

List, Status, and Info

animaworks anima list                    # List all Anima (name, enabled, model, supervisor)
animaworks anima list --local            # Scan filesystem directly (no API)
animaworks anima status                  # All Anima process states (State, Model, PID, Uptime)
animaworks anima status {name}           # Specific Anima process state
animaworks anima info {name}             # Detailed config (model, role, credential, voice, etc.)
animaworks anima info {name} --json      # JSON output

anima info output includes:

• Anima name, Enabled, Role, Model, Execution Mode
• Credential, Fallback Model, Max Turns, Max Chains
• Context Threshold, Max Tokens, LLM Timeout
• Thinking settings, Supervisor, Mode S Auth
• Voice settings (tts_provider, voice_id, speed, pitch)

Create

# Create from character sheet (MD) — recommended
animaworks anima create --from-md {file} [--role {role}] [--name {name}]

# Create from template
animaworks anima create --template {template_name} [--name {name}]

# Create blank
animaworks anima create --name {name}

Enable, Disable, Delete

animaworks anima enable {name}           # Enable (return from pause)
animaworks anima disable {name}          # Disable (pause)
animaworks anima delete {name}           # Delete (after ZIP archive)
animaworks anima delete {name} --no-archive  # Delete without archive
animaworks anima delete {name} --force   # Delete without confirmation
animaworks anima restart {name}          # Restart process
animaworks anima audit {name}            # Comprehensive audit of subordinate's recent activity (default: 1 day)
animaworks anima audit {name} --days 7   # Audit last 7 days

Change Model

animaworks anima set-model {name} {model_name}
animaworks anima set-model {name} {model_name} --credential {credential_name}
animaworks anima set-model --all {model_name}   # Change all Anima at once

Requires anima restart {name} when server is running.

Change Role

# Change role (reapply template + auto restart)
animaworks anima set-role {name} {role}

# Change status.json role field only (do not touch template)
animaworks anima set-role {name} {role} --status-only

# Update files only, no restart
animaworks anima set-role {name} {role} --no-restart

Files updated by set-role:

• status.json — role, model, max_turns updated from role template defaults
• specialty_prompt.md — replaced with role-specific guidelines
• permissions.json — replaced with role-specific tool and command permissions

Valid roles: engineer, researcher, manager, writer, ops, general

Hot Reload

animaworks anima reload {name}           # Reload model config from status.json (no process restart)
animaworks anima reload --all            # Reload all Anima

---

Model Information (models subcommand)

animaworks models list                   # List known models (name, mode, context window, note)
animaworks models list --mode S          # Filter by execution mode (S/C/D/G/A/B)
animaworks models list --json            # JSON output
animaworks models info {model_name}      # Resolved info (execution mode, context window, threshold, source)
animaworks models show                   # Show current models.json contents
animaworks models show --json            # Raw JSON output

Details → reference/operations/model-guide.md

---

Chat and Messaging

# Chat with an Anima (human → Anima)
animaworks chat {name} "message"
animaworks chat {name} "message" --from {sender_name}
animaworks chat {name} "message" --local  # Direct execution (no API)

# Send message between Animas
animaworks send {sender} {recipient} "message"
animaworks send {sender} {recipient} "message" --intent report
animaworks send {sender} {recipient} "message" --intent question
animaworks send {sender} {recipient} "message" --reply-to {message_id}
animaworks send {sender} {recipient} "message" --thread-id {thread_id}

# Manual heartbeat trigger
animaworks heartbeat {name}
animaworks heartbeat {name} --local      # Direct execution (no API)

---

Board (Shared Channels)

animaworks board read {channel}                         # Read channel messages
animaworks board read {channel} --limit 50              # Specify max messages
animaworks board read {channel} --human-only            # Human messages only
animaworks board post {sender} {channel} "text"         # Post to channel
animaworks board dm-history {self} {peer}               # Get DM history
animaworks board dm-history {self} {peer} --limit 50    # Specify max messages

---

Config Management (config subcommand)

animaworks config list                   # List all config values
animaworks config list --section system  # Filter by section
animaworks config list --show-secrets    # Show API key values
animaworks config get {key}              # Get specific value (dot notation: system.log_level)
animaworks config get {key} --show-secrets
animaworks config set {key} {value}      # Set a config value
animaworks config export-sections        # Export to template files
animaworks config export-sections --dry-run

---

Log Viewing (logs)

animaworks logs {name}                   # View specific Anima logs
animaworks logs --all                    # View server + all Anima logs
animaworks logs {name} --lines 100       # Specify line count (default: 50)
animaworks logs {name} --date 20260301   # View logs for specific date

---

Cost Tracking (cost)

animaworks cost                          # Token usage and cost for all Anima
animaworks cost {name}                   # Specific Anima cost
animaworks cost --today                  # Today only
animaworks cost --days 7                 # Last 7 days (default: 30)
animaworks cost --json                   # JSON output

---

Task Management (task subcommand)

animaworks task list                     # List tasks
animaworks task list --status pending    # Filter by status (pending/in_progress/done/cancelled/blocked)
animaworks task add --assignee {name} --instruction "task description"
animaworks task add --assignee {name} --instruction "desc" --source human --deadline 2026-03-10T18:00:00
animaworks task update --task-id {id} --status done
animaworks task update --task-id {id} --status done --summary "completion summary"

---

RAG Index Management

animaworks index                         # Incremental index update for all Anima
animaworks index --anima {name}          # Specific Anima only
animaworks index --full                  # Full reindex of all data
animaworks index --dry-run               # Preview changes only (no execution)

---

Asset Operations

Optimize Assets

animaworks optimize-assets                              # Optimize 3D assets for all Anima
animaworks optimize-assets --anima {name}               # Specific Anima only
animaworks optimize-assets --dry-run                    # Preview only
animaworks optimize-assets --simplify                   # Mesh simplification
animaworks optimize-assets --texture-compress           # Texture compression
animaworks optimize-assets --texture-resize 512         # Texture resize

Remake Assets

animaworks remake-assets {name} --style-from {reference}   # Regenerate assets with style transfer
animaworks remake-assets {name} --style-from {ref} --steps portrait,fullbody
animaworks remake-assets {name} --style-from {ref} --dry-run
animaworks remake-assets {name} --style-from {ref} --no-backup

---

External Tool Execution (animaworks-tool)

Commands for Anima to use external services (Slack, Gmail, GitHub, etc.).

# Show help
animaworks-tool {tool_name} --help

# Execute
animaworks-tool {tool_name} {subcommand} [args...]

# Background execution (for long-running tools)
animaworks-tool submit {tool_name} {subcommand} [args...]

Examples

animaworks-tool web_search query "AnimaWorks framework"
animaworks-tool slack send --channel "#general" --text "Good morning"
animaworks-tool github issues --repo owner/repo
animaworks-tool submit image_gen pipeline "1girl, ..." --anima-dir $ANIMAWORKS_ANIMA_DIR

For submit details → common_knowledge/operations/background-tasks.md

Background Task Monitoring (Anima Internal Tools)

To check progress of tasks submitted via submit, use these internal tools:

• list_background_tasks — List running and completed tasks
• check_background_task(task_id) — Get status and result for a specific task

These are not CLI commands but MCP tools used by Anima during conversation.

---

Initialization and Migration

animaworks init                          # Initialize runtime directory (~/.animaworks/)
animaworks init --force                  # Re-initialize, overwriting existing config
animaworks init --skip-anima             # Skip Anima creation
animaworks migrate-cron                  # Convert cron.md from Japanese format to standard cron

---

Global Options

animaworks --gateway-url http://host:port {command}   # Specify server URL
animaworks --data-dir /path/to/data {command}         # Specify runtime directory