CLI Command Reference

Wunderland defaults to the interactive TUI when launched in a TTY with no subcommand. Use explicit subcommands for scripts, setup, diagnostics, or automation.

Core Commands

Command	Purpose
`wunderland`	Open the TUI dashboard
`wunderland create <description>`	Create an agent from a natural language description
`wunderland new`	Unified interactive agent creation (NL, preset, blank, or import)
`wunderland quickstart`	Auto-detect your environment and scaffold the fastest working setup
`wunderland setup`	Guided initial configuration (QuickStart or Advanced)
`wunderland doctor`	Health and configuration checks
`wunderland connect <service>`	Connect an external service via OAuth or guided setup
`wunderland chat`	Interactive chat from the terminal
`wunderland start`	Start the agent runtime/server
`wunderland init <dir>`	Scaffold a new agent project
`wunderland status`	Runtime and connection status
`wunderland help <topic>`	Short operator guides

Setup & Configuration

`wunderland setup`

Interactive setup wizard. Configures LLM provider, personality, channels, RAG memory, and voice.

wunderland setup           # Interactive mode
wunderland setup --yes     # Auto-accept defaults

QuickStart mode covers 5 steps: LLM provider, personality preset, channels, RAG memory, and voice. Advanced mode adds: custom HEXACO sliders, extensions/skills, security pipeline, and granular TTS/STT customization.

`wunderland quickstart`

One-shot onboarding for the common case.

wunderland quickstart

Use this when you want the shortest path from “nothing configured” to “agent is runnable”.

`wunderland create <description>`

Create an agent from a natural language description. The CLI sends your description to the configured LLM, extracts a full agent configuration (preset, skills, extensions, channels, HEXACO personality, security tier), previews it with confidence scores, and scaffolds a project directory.

wunderland create "A research agent that monitors Hacker News and summarizes daily"
wunderland create "A customer support agent for my SaaS product" --yes
wunderland create "A social media bot for Twitter and Instagram" --managed
wunderland create "A data analyst agent" --dir ./agents/analyst

Flag	Effect
`--yes` / `-y`	Skip confirmation prompt
`--managed`	Restrict to managed-mode capabilities (no filesystem/CLI tools)
`--dir <path>`	Override output directory name
`--update`	Merge with existing agent.config.json in current directory

See the NL Agent Creation guide for tips on writing effective descriptions and details on confidence scores.

`wunderland new`

Unified interactive agent creation entry point. Presents four modes:

From a preset -- select from curated agent presets
Describe in plain English -- NL creation (delegates to wunderland create)
Blank agent -- minimal scaffold for manual configuration
Import manifest -- load from a shared agent.manifest.json

wunderland new                                    # Interactive mode
wunderland new "Build a twitter bot"              # NL mode (auto-detected for 10+ char descriptions)
wunderland new --preset research-assistant        # Direct preset mode
wunderland new --from ./exported-agent.json       # Direct import mode

`wunderland init <dir>`

Scaffold a new agent project from a preset (non-NL path).

wunderland init my-agent
wunderland init my-agent --preset research-assistant
wunderland init my-agent --provider openai --model gpt-4o
wunderland init my-agent --security-tier strict

`wunderland config`

Read and write configuration values.

wunderland config get llmProvider            # Read a value
wunderland config set llmProvider anthropic   # Set a value
wunderland config set llmModel claude-sonnet-4-6
wunderland config set voiceProvider openai
wunderland config set ui.theme cyberpunk

Config is stored at ~/.wunderland/config.json.

`wunderland doctor`

Check configuration, API keys, provider connectivity, and voice readiness.

wunderland doctor

Chat & Runtime

`wunderland chat`

Start an interactive chat session.

wunderland chat                        # Default mode
wunderland chat --provider openai      # Override provider
wunderland chat --model gpt-4o-mini    # Override model
wunderland chat --overdrive            # Auto-approve tool calls
wunderland chat --auto-approve-tools   # Fully autonomous

Config-backed agents also write dated plain-text session logs under ./logs/YYYY-MM-DD/*.log by default.

In-chat commands:

Command	Action
`/help`	Show available commands
`/tools`	List available tools
`/clear`	Clear conversation history
`/exit`	End the session

`wunderland start`

Start the agent runtime server.

wunderland start                    # Default port
wunderland start --port 3001        # Custom port
wunderland start --overdrive        # Auto-approve tools

wunderland start keeps daemon stdout.log / stderr.log in the daemon directory, and also writes dated session logs under the agent folder’s ./logs/YYYY-MM-DD/*.log path by default.

`wunderland status`

Show runtime status, active connections, and persisted LLM usage/cost totals. By default this reads the shared ledger at ~/.framers/usage-ledger.jsonl. Use AGENTOS_USAGE_LEDGER_PATH or WUNDERLAND_USAGE_LEDGER_PATH when you want a different shared file.

wunderland status

Voice Commands

wunderland voice status              # Check provider readiness
wunderland voice tts                 # List TTS providers
wunderland voice stt                 # List STT providers
wunderland voice test "Hello"        # Synthesize a test phrase
wunderland voice clone               # Voice cloning guidance

Details

status — Shows telephony, TTS, and STT provider readiness with configuration details
tts — Lists all text-to-speech providers and whether they are configured
stt — Lists all speech-to-text providers and whether they are configured
test <text> — Synthesizes a short sample through the preferred runtime TTS provider
clone — Explains supported voice-cloning provider paths (ElevenLabs)

Quick Voice Setup

# If you have an OpenAI key, voice is one command:
wunderland config set voiceProvider openai

# Or re-run setup (voice is included in QuickStart)
wunderland setup

Video Commands

wunderland video generate <prompt>             # Generate a video from text
wunderland video generate <prompt> --provider runway    # Use a specific provider
wunderland video generate <prompt> --duration 10        # Duration in seconds
wunderland video generate <prompt> --output ./out.mp4   # Custom output path
wunderland video animate <image> <prompt>      # Animate a still image
wunderland video animate photo.png "slow zoom out, cinematic"
wunderland video analyze <file>                # Analyze a video file
wunderland video analyze clip.mp4              # Scene descriptions, objects, sentiment
wunderland video analyze clip.mp4 --model gpt-4o        # Override vision model

Details

generate — Text-to-video via Runway Gen-3 or Fal.ai. Produces an MP4 file.
animate — Image-to-video. Takes a still image and a motion prompt.
analyze — Runs scene detection, object recognition, and sentiment analysis via a vision-capable LLM.

Requires RUNWAY_API_KEY or FAL_API_KEY for generation. Analysis requires a vision-capable LLM key.

Audio Commands

wunderland audio music <prompt>                # Generate a music track
wunderland audio music "lo-fi hip hop, rainy day"
wunderland audio music <prompt> --provider suno         # Use a specific provider
wunderland audio music <prompt> --duration 30           # Duration in seconds
wunderland audio music <prompt> --output ./track.mp3    # Custom output path
wunderland audio sfx <prompt>                  # Generate a sound effect
wunderland audio sfx "door creaking open slowly"
wunderland audio sfx <prompt> --provider stability      # Use Stable Audio

Details

music — Text-to-music via Suno or Fal.ai. Default duration is 30 seconds.
sfx — Text-to-sound-effect via Stable Audio or Fal.ai. Default duration is 5 seconds.

Requires SUNO_API_KEY, STABILITY_API_KEY, or FAL_API_KEY.

Common Flags (Video & Audio)

Flag	Effect
`--provider <name>`	Override the default provider (runway, fal, suno, stability)
`--model <name>`	Override the model (provider-specific)
`--duration <seconds>`	Set output duration
`--output <path>`	Custom output file path

Extensions & Skills

`wunderland extensions`

wunderland extensions list           # List available extensions
wunderland extensions info image-generation
wunderland extensions enable web-search
wunderland extensions disable giphy
wunderland extensions configure      # Set global provider defaults
wunderland extensions configure image-generation

`wunderland skills`

wunderland skills list               # List available skills
wunderland skills info web-search
wunderland skills enable summarize
wunderland skills disable summarize

`wunderland models`

wunderland models                    # Show current provider/model info

Workflows & Orchestration

`wunderland workflows`

wunderland workflows list            # Find local workflow/mission definition files
wunderland workflows examples        # Show bundled orchestration examples
wunderland help workflows            # Authoring guide: workflow() vs AgentGraph vs mission()

Current CLI status:

list scans conventional authoring directories like ./workflows, ./missions, and ./orchestration
examples points to bundled runnable examples in packages/wunderland/examples/
run executes local YAML workflow definitions in-process through Wunderland’s graph runtime
status and cancel are still backend-oriented paths

For in-process orchestration today:

import { createWunderland } from 'wunderland';
import { workflow } from 'wunderland/workflows';

const app = await createWunderland({ llm: { providerId: 'openai' } });
const compiled = workflow('demo')
  .input({ type: 'object', properties: { topic: { type: 'string' } } })
  .returns({ type: 'object', properties: { summary: { type: 'string' } } })
  .step('draft', { gmi: { instructions: 'Return JSON under artifacts.summary.' } })
  .compile();

const result = await app.runGraph(compiled, { topic: 'agent orchestration' });

Agent Management

`wunderland list-presets`

List all available agent presets.

wunderland list-presets

Presets include: research-assistant, customer-support, coding-agent, creative-writer, and more.

`wunderland seal`

Seal an agent's configuration (immutability).

wunderland seal

`wunderland export` / `wunderland import`

Export and import agent configurations.

wunderland export my-agent.json
wunderland import my-agent.json

`wunderland emergent`

Inspect, export, import, and administer runtime-forged tools.

wunderland emergent list --seed <seedId>
wunderland emergent inspect <name|id> --seed <seedId>
wunderland emergent export <name|id> --seed <seedId> --output ./my-tool.emergent-tool.yaml
wunderland emergent import ./my-tool.emergent-tool.yaml --seed <seedId>
wunderland emergent promote <name|id> --seed <seedId>
wunderland emergent demote <name|id> --seed <seedId>
wunderland emergent audit <name|id> --seed <seedId>

export and import use the portable agentos.emergent-tool.v1 package format. compose tools are portable by default. sandbox tools are portable only when source code is present. Redacted sandbox exports can still be reviewed or committed to Git, but they are intentionally not importable into another runtime.

Agency (Multi-Agent Teams)

`wunderland agency`

Manage multi-agent collectives (agencies).

wunderland agency                                  # Show help
wunderland agency list                             # List configured agencies
wunderland agency list --seed <id>                 # List from backend
wunderland agency status <name>                    # Show agency status and agents
wunderland agency run <name> "<prompt>"            # Execute an agency
wunderland agency run <name> "<prompt>" --stream   # Stream with agent events

`wunderland agency create`

Create a new agency. Accepts either a simple name (shows a manual template) or a natural language description (LLM-powered extraction).

# Manual: shows JSON template
wunderland agency create research-team --strategy graph

# NL-powered: extracts agency name, strategy, agents, roles, and dependencies
wunderland agency create "research team with a researcher, analyst, and writer"
wunderland agency create "debate council where an optimist and pessimist argue, then a moderator synthesizes" --yes

When given a description (20+ characters with spaces), the CLI:

Sends the description to your configured LLM
Extracts: agency name, orchestration strategy, shared goals, and named agents with roles/instructions/dependencies
Previews the extracted configuration
Writes the agency block to agent.config.json (creates or merges)

Flag	Effect
`--strategy <name>`	Override strategy: sequential, parallel, graph, debate, review-loop, hierarchical
`--yes` / `-y`	Skip confirmation prompt
`--seed <id>`	Agent seed ID for backend queries
`--stream`	Stream output with agent events (for `run`)

Ollama (Local LLM)

`wunderland ollama-setup`

Auto-detect hardware, install Ollama, recommend models, and configure.

wunderland ollama-setup              # Interactive
wunderland ollama-setup --yes        # Non-interactive
wunderland ollama-setup --tier mid   # Force tier
wunderland ollama-setup --skip-pull  # Configure without downloading
wunderland ollama-setup mistral:7b   # Override model

Service Connections

`wunderland connect`

Start an OAuth flow or guided setup for external services. Currently supports Gmail, WhatsApp, Slack, and Signal.

wunderland connect                     # Show available services
wunderland connect gmail               # Gmail via Google OAuth
wunderland connect gmail --credentials ~/Downloads/client_secret_*.json
wunderland connect whatsapp            # WhatsApp via Twilio or Meta Cloud API
wunderland connect slack               # Slack via OAuth (Rabbithole)
wunderland connect signal              # Signal via signal-cli wizard

Flag	Effect
`--credentials <path>`	Path to a Google OAuth client secret JSON file (Gmail only). Accepts both `{"installed": {...}}` and `{"web": {...}}` wrapper formats.

After a successful OAuth flow, tokens are saved to ~/.wunderland/config.json and automatically loaded on the next wunderland chat or wunderland start.

Agentic credential setup: You can also ask the agent to guide you through credential setup interactively:

wunderland "help me set up Gmail"
wunderland "I downloaded a Google client secret, help me connect"
wunderland "configure slack integration"

The NL intent router detects connection-related input and routes it to the connect flow. The agent uses bundled platform knowledge to know what each service requires and can find downloaded credential files on your system.

Authentication

`wunderland login`

Authenticate with a ChatGPT subscription (OpenAI OAuth).

wunderland login

`wunderland auth-status`

Check current authentication state.

wunderland auth-status

`wunderland logout`

Remove stored OAuth tokens.

wunderland logout

Workflows & Scheduling

`wunderland workflows`

wunderland workflows list                          # Discover local workflow/mission files
wunderland workflows examples                      # Show bundled orchestration examples
wunderland workflows run workflows/research.workflow.yaml      # Execute a workflow
wunderland workflows explain workflows/research.workflow.yaml  # Print the compiled graph
wunderland workflows status <id>                  # Backend workflow status
wunderland workflows cancel <id>                  # Backend workflow cancellation

`wunderland cron`

wunderland cron add "0 9 * * 1-5" daily-report  # Schedule
wunderland cron list                              # List jobs
wunderland cron remove <job-id>                   # Remove
wunderland cron pause <job-id>                    # Pause
wunderland cron resume <job-id>                   # Resume

Help Topics

wunderland help getting-started    # First-run guide
wunderland help voice              # Voice/speech setup
wunderland help llm                # LLM provider info
wunderland help auth               # OAuth and API keys
wunderland help tui                # TUI dashboard usage
wunderland help presets            # Agent presets
wunderland help security           # Approvals and permissions
wunderland help faq                # Frequently asked questions
wunderland help ui                 # Themes and ASCII mode
wunderland help export             # PNG export

Global Flags

Flag	Effect
`--yes` / `-y`	Auto-confirm prompts
`--dry-run`	Show what would happen without writing
`--config <path>`	Override config directory
`--theme <name>`	Set UI theme (`cyberpunk`, `plain`)
`--ascii`	Force ASCII-only glyphs
`--no-color`	Disable colors
`--overdrive`	Auto-approve tool calls
`--auto-approve-tools`	Fully autonomous tool execution
`--llm-judge`	Use an LLM as judge for tool approval decisions instead of interactive prompts
`--no-guardrail-override`	Disable post-approval guardrail safety net (code-safety, pii-redaction)
`--dangerously-skip-permissions`	Skip permission checks
`--dangerously-skip-command-safety`	Disable shell safety checks
`--export-png <path>`	Export command output as PNG

Common Operator Flows

NL Agent Creation

wunderland create "A research assistant that searches the web and summarizes articles"
cd seed_research_assistant
cp .env.example .env
wunderland start

First-Time Setup

wunderland setup
wunderland doctor
wunderland chat

Daily Development

wunderland start          # Terminal 1
wunderland chat           # Terminal 2

Voice Testing

wunderland voice status
wunderland voice test "Hello from Wunderland"

Provider Switching

wunderland config set llmProvider anthropic
wunderland config set llmModel claude-sonnet-4-6
wunderland doctor   # verify
wunderland chat     # test

For the runtime-backed voice path, see the Voice Runtime guide.

Natural Language Routing

When Wunderland receives input that doesn't match a known command, it runs a keyword-based intent classifier to route the input to the appropriate handler. This is instant (no LLM call) and deterministic.

How It Works

The CLI joins all non-flag positional arguments and checks them against keyword patterns in priority order:

agency -- input mentions a collective noun (team, crew, squad, group, agency, collective) AND a creation verb (build, create, make, etc.)
create -- input mentions a creation verb AND an agent noun (agent, bot, assistant, wunderbot)
connect -- input mentions a connection verb (connect, set up, configure, link, add, enable) AND a service keyword (gmail, email, google, whatsapp, slack, signal), or references credential files / client secrets
mission -- input contains a research/investigation verb AND is longer than 50 characters
help -- input contains a question word (what, how, why, etc.) AND ends with ?
chat -- everything else (default fallback)

Priority matters: "Create a team of agents" routes to agency (not create) because team nouns are checked first. General credential questions ("how do I add API keys?") route to help/chat so the agent can guide interactively.

Examples

# These are all valid top-level invocations:
wunderland "Build me a research agent that monitors AI news"
# → Detected intent: create agent → running "wunderland create"

wunderland "Create a team: researcher, analyst, writer"
# → Detected intent: create agency → running "wunderland agency create"

wunderland "Research the latest advances in RAG and write a comprehensive report"
# → Detected intent: run mission → running "wunderland mission"

wunderland "What LLM providers do you support?"
# → Detected intent: answer question → running "wunderland chat"

wunderland "Hello, how are you today"
# → Detected intent: chat → running "wunderland chat"

Intent Table

Intent	Routes to	Trigger Pattern
`create`	`wunderland create`	Creation verb + agent noun
`agency`	`wunderland agency create`	Creation verb + collective noun
`connect`	`wunderland connect`	Connection verb + service keyword, or credential file reference
`mission`	`wunderland mission`	Research verb + 50+ char input
`help`	`wunderland chat`	Question word + trailing `?`
`chat`	`wunderland chat`	Everything else

Short unrecognized input (5 characters or fewer) still produces the standard "unknown command" error.

Core Commands​

Setup & Configuration​

wunderland setup​

wunderland quickstart​

wunderland create <description>​

wunderland new​

wunderland init <dir>​

wunderland config​

wunderland doctor​

Chat & Runtime​

wunderland chat​

wunderland start​

wunderland status​

Voice Commands​

Details​

Quick Voice Setup​

Video Commands​

Details​

Audio Commands​

Details​

Common Flags (Video & Audio)​

Extensions & Skills​

wunderland extensions​

wunderland skills​

wunderland models​

Workflows & Orchestration​

wunderland workflows​

Agent Management​

wunderland list-presets​

wunderland seal​

wunderland export / wunderland import​

wunderland emergent​

Agency (Multi-Agent Teams)​

wunderland agency​

wunderland agency create​

Ollama (Local LLM)​

wunderland ollama-setup​

Service Connections​

wunderland connect​

Authentication​

wunderland login​

wunderland auth-status​

wunderland logout​

Workflows & Scheduling​

wunderland workflows​

wunderland cron​

Help Topics​

Global Flags​

Common Operator Flows​

NL Agent Creation​

First-Time Setup​

Daily Development​

Voice Testing​

Provider Switching​

Natural Language Routing​

How It Works​

Examples​

Intent Table​

Core Commands

Setup & Configuration

`wunderland setup`

`wunderland quickstart`

`wunderland create <description>`

`wunderland new`

`wunderland init <dir>`

`wunderland config`

`wunderland doctor`

Chat & Runtime

`wunderland chat`

`wunderland start`

`wunderland status`

Voice Commands

Details

Quick Voice Setup

Video Commands

Details

Audio Commands

Details

Common Flags (Video & Audio)

Extensions & Skills

`wunderland extensions`

`wunderland skills`

`wunderland models`

Workflows & Orchestration

`wunderland workflows`

Agent Management

`wunderland list-presets`

`wunderland seal`

`wunderland export` / `wunderland import`

`wunderland emergent`

Agency (Multi-Agent Teams)

`wunderland agency`

`wunderland agency create`

Ollama (Local LLM)

`wunderland ollama-setup`

Service Connections

`wunderland connect`

Authentication

`wunderland login`

`wunderland auth-status`

`wunderland logout`

Workflows & Scheduling

`wunderland workflows`

`wunderland cron`

Help Topics

Global Flags

Common Operator Flows

NL Agent Creation

First-Time Setup

Daily Development

Voice Testing

Provider Switching

Natural Language Routing

How It Works

Examples

Intent Table