CLI Commands

Complete reference for the Moxxy CLI (@moxxy/cli).

Overview

The Moxxy CLI is a Node.js (22+) package built with TypeScript, @clack/prompts, and Ink 6.0 (React-based TUI). It manages the moxxy-gateway Rust binary and provides interactive setup workflows.

npx @moxxy/cli <command> [options]
# or if installed globally:
moxxy <command> [options]

Global Options

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

Commands Reference

Command	Description
init	Interactive setup wizard
gateway	Manage the gateway daemon
channel	Configure messaging channels

---

init

Run the interactive setup wizard to configure Moxxy for first use.

moxxy init

What It Does

1. Walks you through LLM provider selection (Anthropic, OpenAI, Ollama, or OpenAI-compatible)
2. Prompts for the selected provider's API key
3. Generates the first API token (bearer token with mox_ prefix)
4. Optionally configures a Telegram channel
5. Downloads the moxxy-gateway binary to ~/.moxxy/bin/ if not already present
6. Initializes the SQLite database (~/.moxxy/moxxy.db)

Example

$ moxxy init

  Welcome to moxxy!

  ? Select your LLM provider:
    > Anthropic (Claude)
      OpenAI
      Ollama
      OpenAI-compatible

  ? Enter your Anthropic API key: sk-ant-***

  Your first API token: mox_a1b2c3d4e5f6...

  ? Set up Telegram channel? (Y/n)

  Gateway binary downloaded to ~/.moxxy/bin/moxxy-gateway
  Configuration saved to ~/.moxxy/

  Run 'moxxy gateway start' to begin!

---

gateway

Manage the moxxy-gateway background daemon.

moxxy gateway <subcommand>

Subcommands

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

The CLI auto-downloads the moxxy-gateway Rust binary to ~/.moxxy/bin/ if it is not already present.

See Gateway for detailed documentation on the gateway architecture and startup sequence.

start

moxxy gateway start

Starts the moxxy-gateway binary, which initializes the Axum HTTP server on port 3000 (default), opens the SQLite database, loads channel bridges, and begins processing.

stop

moxxy gateway stop

Sends a graceful shutdown signal to the running gateway process.

restart

moxxy gateway restart

Performs a stop followed by a start.

status

moxxy gateway status

Shows whether the gateway is running, its PID, uptime, and connected channels.

---

channel

Configure messaging channel connections.

moxxy channel <type> [options]

Available Channels

Type	Description
telegram	Configure Telegram bot
discord	Configure Discord bot

Telegram

moxxy channel telegram --agent <name>

Interactive setup that prompts for a bot token from @BotFather, then walks through the pairing code flow.

See Channels for detailed setup instructions.

Discord

moxxy channel discord --agent <name>

Interactive setup that prompts for a Discord bot token. Requires Message Content Intent to be enabled.

See Channels for detailed setup instructions.

---

Environment Variables

Moxxy respects the following environment variables:

Variable	Default	Description
MOXXY_HOME	~/.moxxy	Root data directory
MOXXY_HOST	127.0.0.1	Gateway bind address
MOXXY_PORT	3000	Gateway listen port
MOXXY_API_URL	http://127.0.0.1:3000	Full API base URL
MOXXY_TOKEN	-	Bearer token for API authentication
MOXXY_LOOPBACK	-	Enable loopback mode (bypasses auth for localhost)
MOXXY_VAULT_KEY	-	Override vault encryption key
MOXXY_DB_PATH	~/.moxxy/moxxy.db	SQLite database path
MOXXY_GATEWAY_URL	-	Gateway binary download URL override
MOXXY_CORS_ORIGINS	-	Allowed CORS origins (comma-separated)
ANTHROPIC_API_KEY	-	Anthropic API key
OPENAI_API_KEY	-	OpenAI API key

---

Exit Codes

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