CLI Commands

The zubo CLI manages your agent. Here's every command.

Copy-Paste Task Cards

zubo config set auth.enabled true
zubo auth create-key my-app

zubo config set failover '["openai","ollama"]'
zubo config set providers.ollama.model llama3.3

Common Errors

curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3000/api/dashboard/status

zubo model openai/gpt-4o-mini
zubo logs --follow

ollama serve
ollama pull llama3.3

Most-Used Commands

zubo setup
zubo start
zubo status
zubo logs --follow
zubo model
zubo config get
zubo config set budget.dailyLimitUsd 5
zubo eval

Use CLI commands for automation, CI, and system management. Use slash commands in chat for fast runtime actions like /model set and /permissions set.

Core Commands

zubo setup

Interactive setup wizard for first-time configuration. You can choose a Quickstart profile (~5 minutes) or the full setup flow. You can also choose two UI modes:

• Terminal — Classic step-by-step prompts right in your terminal.
• Dashboard — Opens a beautiful browser-based wizard at http://localhost:<port> with the same steps, auto-detection of local providers (Ollama, LM Studio), and connection testing. Great for non-technical users or if you prefer a visual UI.

The full setup mode walks you through 4 steps:

1. LLM Provider — Choose from 15 supported providers (Anthropic, OpenAI, Ollama, Groq, Together, OpenRouter, DeepSeek, xAI, MiniMax, Fireworks, Cerebras, LM Studio, Claude Code, Codex, or any OpenAI-compatible endpoint). Enter your API key and select a model. Optionally add a fallback provider for automatic failover.
2. Channels — Enable any of 7 messaging channels: Telegram, Discord, Slack, WhatsApp, Signal, and Email. WebChat is always enabled by default. Each channel prompts for its required credentials (bot tokens, webhook URLs, etc.).
3. Personalization — Name your agent and optionally describe its personality. The name and personality are used in the system prompt and across all channels.
4. Smart Routing — Optionally set up a fast provider for simple queries (e.g., greetings, factual lookups). Smart routing automatically directs simple messages to a cheaper, faster model while using the primary model for complex tasks — saving 50–80% on costs.

Writes to ~/.zubo/config.json. You can re-run zubo setup at any time to reconfigure.

zubo setup

zubo start

Start the Zubo agent. Opens the web dashboard in your browser.

zubo start           # Foreground mode
zubo start --daemon  # Background mode

In foreground mode, logs are printed directly to the terminal. In daemon mode, the agent runs in the background and logs are written to a file. Use zubo logs to view them.

zubo stop

Stop the background daemon. This sends a shutdown signal to the running daemon process.

zubo stop

zubo status

Show current status: provider, model, channels, process state.

zubo status

Logs

zubo logs            # Show last 50 lines
zubo logs --follow   # Stream logs live (like tail -f)
zubo logs -f         # Short form

When using --follow or -f, new log entries are streamed to your terminal in real time. Press Ctrl+C to stop following.

Model Management

zubo model           # Show active provider/model
zubo model --list    # List all configured providers
zubo model ollama/llama3.3  # Switch to provider/model

The model argument uses the format provider/model. For example, anthropic/claude-sonnet-4-5-20250929, openai/gpt-4o, or ollama/llama3.3. The change takes effect immediately if the agent is running.

In chat channels, use slash commands for the same actions: /model and /model set <provider/model>.

In-Chat Slash Commands

/help
/status
/memory <query>
/model
/model set <provider/model>
/tools [filter]
/permissions <tool>
/permissions set <tool> <auto|confirm|deny>
/budget
/budget pause
/budget resume

These commands work in WebChat and supported messaging channels. Use them for quick operations without leaving chat.

Configuration

zubo config set <key> <value>    # Set a config value
zubo config get [key]            # Get config value(s)

Examples:

zubo config set activeProvider ollama
zubo config set model llama3.3
zubo config set heartbeatMinutes 60
zubo config set auth.enabled true
zubo config set rateLimit.chatPerMinute 30
zubo config set channels.webchat.port 3000
zubo config get                          # Show all config (keys masked)
zubo config get activeProvider           # Show single value

Supports dotted keys for nested values (e.g., auth.enabled sets the enabled field inside the auth object). Values are auto-parsed: true/false become booleans, digit strings become numbers, and everything else is stored as a string.

These commands are the CLI equivalents of the config_update tool and the PUT /api/dashboard/config API endpoint. All three interfaces use the same dot-notation paths and schema validation.

Skills

zubo skills          # Interactive menu
zubo skills list     # List installed skills
zubo skills new      # Create a new skill (wizard)
zubo skills remove   # Remove a skill
zubo skills reinstall # Reinstall built-in skills

The interactive menu (zubo skills with no subcommand) presents a selection interface for all skill management operations. Use the subcommands for non-interactive or scripted usage.

Skill Registry

zubo install <name>  # Install skill from registry
zubo search <query>  # Search the registry
zubo publish [name]  # Publish a skill

zubo install downloads and installs the named skill from the community registry into ~/.zubo/skills/. zubo search returns matching skills with their names and descriptions. zubo publish validates and submits the current skill directory (or the named skill) to the registry.

Voice

zubo voice           # Start continuous voice conversation mode

Starts an interactive voice conversation loop. Zubo listens through your microphone, transcribes speech using Whisper (cloud or local whisper.cpp), processes it through the agent, and speaks the response back using text-to-speech. Requires voice.stt and voice.tts to be configured. Install sox for microphone recording.

Reliability Eval

zubo eval            # Run reliability + safety checks

Runs deterministic checks for slash command behavior, memory explainability metadata, and dry-run tool safety. Useful before deploying config changes or upgrading Zubo.

Authentication

zubo auth create-key [label]  # Create API key (shown once)
zubo auth list-keys           # List all keys
zubo auth delete-key <id>     # Delete a key

API keys are used when auth.enabled is true. The key value is displayed only once at creation time — store it securely. The optional label helps you identify the key later. Use zubo auth list-keys to see all keys with their IDs, labels, and last-used dates.

Data Management

zubo export                      # Export as JSON
zubo export --format sqlite      # Backup as SQLite file
zubo export --output backup.json # Custom output path
zubo import <path>               # Import from JSON

The JSON export includes conversations, memory chunks, settings, analytics, and uploaded file metadata. The SQLite backup creates a copy of the raw database file. Import restores data from a previously exported JSON file.

MCP Server

zubo mcp-serve              # Start MCP server over stdio
zubo mcp-serve --port 9800  # Start MCP server over HTTP (SSE)

Runs Zubo as an MCP (Model Context Protocol) server, exposing all of Zubo's tools to external MCP clients such as Claude Code or OpenAI Codex. By default, the server communicates over stdio using JSON-RPC. Use the --port flag to start an HTTP-based server with Server-Sent Events instead.

When an MCP client connects, it can discover and call any of Zubo's built-in tools and installed skill tools — including memory search, knowledge graph queries, calendar access, GitHub operations, scheduling, and more.

Example: Claude Code

Add Zubo to your Claude Code MCP config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zubo": {
      "command": "zubo",
      "args": ["mcp-serve"]
    }
  }
}

Example: OpenAI Codex

Add Zubo to your Codex MCP configuration:

{
  "mcpServers": {
    "zubo": {
      "command": "zubo",
      "args": ["mcp-serve"]
    }
  }
}

See Integrations → MCP Server Mode for a full list of exposed tools.

Command Summary

Exit Codes

Environment Variables