CLI Cheatsheet

Quick reference for all MUXI CLI commands

The CLI is your primary tool for creating, developing, deploying, and managing MUXI formations.

Getting Started

# Check version
muxi --version

# Upgrade to latest
muxi upgrade

# Get help
muxi --help
muxi <command> --help

Create

# Create new formation
muxi new formation my-assistant
muxi new formation my-bot --template research

# Add components to formation
muxi new agent researcher
muxi new mcp web-search
muxi new trigger github-issue
muxi new sop customer-onboarding

Local Development

Think of muxi up / muxi down like docker compose up / docker compose down:

# Start server (first terminal)
muxi-server start

# Start formation (second terminal)
cd my-formation
muxi up                      # Start from formation directory

# Formation runs at http://localhost:7890/draft/my-formation

# Stop formation
muxi down                    # Stop (ID from current dir)
muxi down my-bot             # Stop by ID from anywhere

# Server keeps running - stop with: muxi-server stop

Key differences from muxi deploy:

  • Runs directly from source (no bundle/upload)
  • Uses /draft/{id} URL prefix (live uses /api/{id})
  • Fast iteration - instant start

Draft mode: After muxi up, the CLI prompts to enable draft mode. When enabled, all commands (chat, logs, etc.) automatically route to the draft formation. muxi down disables it. You can also use --draft on any command explicitly.

Develop

# Validate formation
muxi validate

# Interactive chat
muxi chat
muxi chat "Hello!"
muxi chat --agent researcher "Find info on X"

Secrets

# Setup wizard (scans formation, prompts for all)
muxi secrets setup

# Individual secrets
muxi secrets set OPENAI_API_KEY
muxi secrets get OPENAI_API_KEY
muxi secrets list
muxi secrets delete OLD_KEY

Configure Formation

# LLM providers and models
muxi config llm              # Interactive wizard
muxi config llm --remote     # View remote config

# Overlord soul and behavior
muxi config overlord         # Configure soul, response format
muxi config overlord --remote

# Other configuration
muxi config memory           # Memory settings
muxi config logging          # Logging streams
muxi config async            # Async response settings
muxi config a2a              # Agent-to-Agent communication
muxi config security         # User credential handling

Deploy

# Deploy to default profile
muxi deploy

# Deploy to specific profile
muxi deploy --profile production

# Validate without deploying
muxi deploy --validate

# Dry run
muxi deploy --dry-run

# Bump version before deploying updates
muxi bump              # Patch: 1.0.0 -> 1.0.1
muxi bump minor        # Minor: 1.0.0 -> 1.1.0
muxi bump major        # Major: 1.0.0 -> 2.0.0
muxi bump --set 2.0.0  # Set specific version

Formations (Remote)

# List formations
muxi server list
muxi server list --profile production

# Get details
muxi server get my-assistant
# Or from formation directory:
muxi get

# Lifecycle
muxi server stop my-assistant
muxi server start my-assistant
muxi server restart my-assistant
# Or from formation directory:
muxi stop
muxi start
muxi restart

# Delete
muxi server delete my-assistant
muxi server delete my-assistant --force
# Or from formation directory:
muxi delete

# Rollback
muxi server rollback my-assistant
# Or from formation directory:
muxi rollback

# Download from server to local
muxi download                    # In formation dir: replace with server version
muxi download my-bot             # Outside: create ./my-bot/ with server version
muxi download --profile prod     # Use specific profile
muxi download --include-db       # Include memory.db from server

Console

# Open MUXI Console in browser
muxi console                     # Opens console, auto-detects formation context
muxi console --profile prod      # Use specific profile

Logs

# View logs
muxi logs my-assistant
muxi logs my-assistant --lines 100
muxi logs my-assistant --follow
muxi logs --mcp                    # MCP tool logs

Registry

# Search
muxi search "customer support"
muxi search --tag research

# Pull
muxi pull @muxi/hello-muxi
muxi pull @muxi/hello-muxi@1.0.0
muxi pull @muxi/hello-muxi --output ~/formations/

# Show details
muxi show @muxi/hello-muxi

# Push
muxi login
muxi push
muxi push --tag v1.0.0
muxi push --dry-run
muxi push --org my-org          # Publish under organization (admin only)

# Organizations
muxi registry orgs              # List orgs and publish permissions

Profiles

# Manage profiles
muxi profiles add production
muxi profiles list
muxi profiles remove old-server

# Set default profile
muxi set default profile production

Formation Info

# View formation status (requires deployed formation)
muxi info
muxi info --full       # Include detailed config
muxi info -f my-bot    # Specify formation

Sessions

# Manage user sessions
muxi sessions list -u user123
muxi sessions show <session_id> -u user123
muxi sessions messages <session_id> -u user123

Requests

# Track and manage chat requests
muxi requests list -u user123
muxi requests show <request_id> -u user123
muxi requests cancel <request_id> -u user123   # Cancel in-progress request

Memory

# View memory config
muxi memory status

# Manage user memories
muxi memory list -u user123
muxi memory add -u user123 --type preference --detail "Prefers formal tone"
muxi memory delete <memory_id> -u user123

# Buffer management
muxi memory buffer -u user123           # View user buffer
muxi memory buffer --clear -u user123   # Clear user buffer
muxi memory buffer --stats              # View buffer stats

Agents (Remote)

# View agents in running formation
muxi agents list
muxi agents show researcher

MCP Servers (Remote)

# View MCP servers in running formation
muxi mcp list
muxi mcp show web-search
muxi mcp tools              # List all available tools

SOPs

# View Standard Operating Procedures
muxi sops list
muxi sops show customer-onboarding

Triggers

# Manage and run triggers
muxi triggers list
muxi triggers show github-issue
muxi triggers run github-issue --data '{"repo": "muxi-ai/cli"}'
muxi triggers run daily-report --async    # Run asynchronously

Scheduler

# View scheduler config and jobs
muxi scheduler status
muxi scheduler list
muxi scheduler show <job_id>

# Manage scheduled jobs
muxi scheduler add --schedule "0 9 * * *" --message "Daily summary"
muxi scheduler remove <job_id>

Artifacts

When formations generate files (PDFs, images, data files), they are saved to ~/.muxi/cli/artifacts/{formation-id}/.

# List saved artifacts (scoped to current formation if in formation dir)
muxi artifacts list
muxi artifacts list --formation my-bot    # List for specific formation

# Open artifacts directory in file manager
muxi artifacts open

# Clean up artifacts
muxi artifacts cleanup                    # Remove all (current formation if in dir)
muxi artifacts cleanup --days 30          # Remove files older than 30 days
muxi artifacts cleanup --formation my-bot # Clean specific formation

Saved Formations

# Save formation configs for quick access
muxi formations add my-bot --profile production --user user123
muxi formations list
muxi formations show my-bot
muxi formations remove my-bot

# Then use from anywhere
muxi info -f my-bot
muxi chat -f my-bot

Upgrade

# Check for updates and upgrade
muxi upgrade

The CLI automatically checks for updates and shows a notification:

[*] MUXI CLI 0.20260210.0 available (current: 0.20260203.0)
    Run: muxi upgrade

muxi upgrade detects your install method:

  • Homebrew: Shows brew upgrade muxi
  • Go install: Shows go install github.com/muxi-ai/cli@latest
  • Binary: Downloads and self-updates from GitHub releases

Disable update checks: export MUXI_NO_UPDATE_CHECK=1

Flags Reference

Global Flags

Flag Description
--profile <name> Use specific server profile
--output json JSON output format
--quiet Suppress non-essential output
--verbose Verbose output
--help Show help

Common Flags

Command Flag Description
deploy --validate Validate only
deploy --dry-run Show what would deploy
bump --set <ver> Set specific version
server delete --force Skip confirmation
logs --follow Stream logs
logs --lines <n> Number of lines
pull --output <dir> Output directory
push --dry-run Preview without publishing
push --org <name> Publish under organization
dev --port <n> Override port
dev --reindex Force reindex
info --full Show full configuration
sessions -u <user> User ID (required)
memory -u <user> User ID for user-scoped ops
memory buffer --clear Clear buffer
memory buffer --stats Show buffer statistics
triggers run --data <json> Trigger input data
triggers run --async Run asynchronously
scheduler add --schedule Cron schedule
download -f, --force Skip confirmation
download -p, --profile Server profile
download --include-db Include memory.db
deploy --include-db Include memory.db
chat, logs, info... --draft Use draft mode (local dev)
artifacts cleanup --days <n> Remove files older than N days
artifacts * --formation Scope to specific formation

Examples

Full Workflow

# Create and develop
muxi new formation my-bot
cd my-bot
muxi secrets setup
muxi dev

# Test
muxi chat "Hello!"

# Deploy
muxi deploy --profile production

# Monitor
muxi logs my-bot --follow

CI/CD

# In CI pipeline
muxi deploy --validate
muxi deploy --profile production
muxi server get my-bot

Registry Workflow

# Contribute a formation
muxi new formation awesome-agent
# ... build it ...
muxi login
muxi push

# Use someone else's
muxi pull @alice/awesome-agent
muxi secrets setup
muxi dev
Home Registry Documentation Star on GitHub
Get priority support