CLI Commands

Complete reference for all Moxxy CLI commands.

Overview

moxxy <command> [options]

Global Options

Option	Description
-h, --help	Show help information
--version	Show version information

Commands Reference

Command	Description
init	First-time setup wizard
web	Start the web dashboard
tui	Start the terminal UI
gateway	Manage the background daemon
logs	Follow real-time daemon logs
run	Execute a single prompt
channel	Manage channel connections
agent	Manage agents
doctor	System diagnostics
dev	Development mode

---

init

Run the first-time setup wizard to configure LLM providers and create your default agent.

moxxy init

What It Does

1. Creates the ~/.moxxy/ directory structure
2. Prompts for LLM provider selection (OpenAI, Google, Z.Ai)
3. Securely stores your API key in the vault
4. Creates a default agent with standard configuration

Example

$ moxxy init

  ◉ Welcome to moxxy!

  ? Select your LLM provider:
    ❯ OpenAI
      Google Gemini
      Z.Ai (Grok)

  ? Enter your OpenAI API key: sk-***

  ✓ Created default agent at ~/.moxxy/agents/default
  ✓ Configuration saved

  Run 'moxxy gateway start' to begin!

---

web

Start the web dashboard for interacting with your agents through a browser interface.

moxxy web [options]

Prerequisites

The gateway must be running:

moxxy gateway start

Options

Option	Default	Description
--port	3001	Port for the web server
--api-host	127.0.0.1	API server host
--api-port	17890	API server port

Example

moxxy web --port 8080

The dashboard will be available at http://127.0.0.1:8080.

Features

• Chat Panel - Conversational interface with streaming responses
• Skills Manager - View, install, and manage agent skills
• Memory Viewer - Inspect short-term and long-term memory
• Channel Config - Set up Telegram, Discord, Slack, WhatsApp
• Vault Manager - Securely store and manage secrets
• Schedule Manager - Create and manage scheduled jobs

---

tui

Start the interactive terminal user interface for chatting with agents.

moxxy tui [options]

Prerequisites

The gateway must be running:

moxxy gateway start

Options

Option	Default	Description
--api-url	http://127.0.0.1:17890	API endpoint URL

Keyboard Shortcuts

Key	Action
Enter	Send message
Ctrl+C	Exit
Ctrl+L	Clear screen

Slash Commands

Command	Description
/help	Show available commands
/clear	Clear chat history
/agent <name>	Switch to a different agent
/new	Start a new session
/quit	Exit the TUI

Example

$ moxxy tui

  ┌─────────────────────────────────────────────────┐
  │ moxxy TUI • Agent: default                      │
  ├─────────────────────────────────────────────────┤
  │                                                 │
  │ You: Hello! What can you do?                    │
  │                                                 │
  │ Agent: I can help you with various tasks using  │
  │ my skills. I can execute shell commands, run    │
  │ Python scripts, fetch web content, and more!    │
  │                                                 │
  ├─────────────────────────────────────────────────┤
  │ > _                                             │
  └─────────────────────────────────────────────────┘

---

gateway

Manage the background daemon process that runs agents.

moxxy gateway <subcommand> [options]

Subcommands

Subcommand	Description
start	Start the gateway daemon
stop	Stop the gateway daemon
restart	Restart the gateway daemon
status	Check gateway status

start

moxxy gateway start

Starts the background daemon that:

• Loads all agents
• Initializes the API server
• Connects configured channels
• Begins scheduled job execution

stop

moxxy gateway stop

Gracefully shuts down the daemon.

restart

moxxy gateway restart

Performs a stop followed by a start. Useful for reloading configuration.

status

moxxy gateway status

Shows:

• Whether the daemon is running
• Process ID
• Uptime
• Connected channels

Example Output

$ moxxy gateway status

  ● Gateway Status: Running
  │
  ├─ PID:        12345
  ├─ Uptime:     2h 34m 12s
  ├─ API:        http://127.0.0.1:17890
  ├─ Agents:     3 active
  │
  └─ Channels:
     ├─ Telegram: @my_bot (connected)
     └─ Discord:  MyServer (connected)

---

logs

Follow real-time logs from the gateway daemon.

moxxy logs

Output

Shows:

• Agent activations
• Skill invocations
• LLM requests/responses
• Channel events
• Errors and warnings

Example

$ moxxy logs

  2024-01-15 10:23:45 INFO  gateway started on :17890
  2024-01-15 10:23:46 INFO  agent 'default' booted
  2024-01-15 10:24:01 INFO  [default] brain activated by TELEGRAM
  2024-01-15 10:24:01 INFO  [default] invoking skill: host_shell
  2024-01-15 10:24:02 INFO  [default] skill completed in 0.8s

Press Ctrl+C to stop following logs.

---

run

Execute a single prompt programmatically without starting an interactive session.

moxxy run --agent <name> --prompt "<prompt>"

Options

Option	Required	Description
--agent, -a	No (default: "default")	Agent to use
--prompt, -p	Yes	The prompt to send

Example

moxxy run --agent default --prompt "What files are in my home directory?"

Use Cases

• Scripted automation
• CI/CD pipelines
• Quick one-off queries
• Testing agent responses

Output Format

The response is printed to stdout, making it easy to capture:

result=$(moxxy run --agent researcher --prompt "Summarize the latest news about AI")
echo "$result"

---

channel

Manage channel connections for messaging platforms.

moxxy channel <type> [options]

Available Channels

Type	Description
telegram	Configure Telegram bot
discord	Configure Discord bot
slack	Configure Slack bot
whatsapp	Configure WhatsApp bridge

Telegram

moxxy channel telegram --agent <name> [--token <bot_token>] [--pair-code <code>]

Option	Description
--agent, -a	Agent to connect (default: "default")
--token	Telegram bot token (will prompt if omitted)
--pair-code, -c	Pairing code from /start command

See Telegram Channel for detailed setup.

Example

$ moxxy channel telegram --agent default

  ◉ Setting up Telegram channel...

  ? Enter your bot token (from @BotFather): 123456:ABC***

  ✓ Bot configured!

  Now send /start to your bot on Telegram.
  Then enter the 6-digit pairing code you receive.

  ? Pairing code: 123456

  ✓ Telegram channel connected!

---

agent

Manage individual agents.

moxxy agent <subcommand> <name> [options]

Subcommands

Subcommand	Description
restart	Restart an agent
remove	Remove an agent
list	List all agents

restart

moxxy agent restart <name>

Reloads the agent's configuration and persona.

remove

moxxy agent remove <name>

Deletes the agent's workspace including:

• Persona file
• Memory database
• Vault
• Custom skills

WARNING

This action is irreversible. The agent's data will be permanently deleted.

list

moxxy agent list

Shows all configured agents and their status.

---

doctor

Run system diagnostics to verify your Moxxy installation.

moxxy doctor [--fix]

Checks

Check	Description
SQLite	Verifies SQLite3 is installed and accessible
Directory	Checks ~/.moxxy/ directory permissions
Gateway	Verifies gateway process is running
LLM Config	Validates LLM provider configuration
Channels	Checks channel connection status

Options

Option	Description
--fix	Attempt to automatically fix issues

Example

$ moxxy doctor

  ✓ SQLite3: installed (3.42.0)
  ✓ Directory: ~/.moxxy/ writable
  ✓ Gateway: running (PID 12345)
  ✓ LLM Config: OpenAI configured
  ✓ Memory: default agent database healthy

  All checks passed!

---

dev

Start the daemon in development mode with elevated permissions.

moxxy dev

Dev Mode Features

• Enables the evolve_core skill for self-modification
• Allows agents to modify framework code
• Disables certain safety restrictions
• Enables detailed debug logging

WARNING

Dev mode is intended for development and experimentation. Use with caution in production environments.

Use Cases

• Developing new skills
• Testing framework modifications
• Debugging agent behavior
• Research and experimentation

---

Environment Variables

Moxxy respects these environment variables:

Variable	Description
MOXXY_API_BASE	Override API base URL
MOXXY_INTERNAL_TOKEN	Internal authentication token
MOXXY_SOURCE_DIR	Override source directory for dev mode
MOXXY_ARGS_MODE	Argument parsing mode

---

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Network error
4	Authentication error