What this package is

@moxxy/cli is the published moxxy binary. It bundles the framework runtime, every built-in mode, every built-in provider, every built-in plugin, the Ink TUI channel, MCP support, the scheduler, webhooks, and the OS service installer into a single executable.

Install this if you want to use moxxy. If you want to author plugins, depend on @moxxy/sdk instead.

What you get out of the box

• A complete agent stack with Anthropic, OpenAI, and ChatGPT (OAuth) providers.
• Three loop modes: default (Claude-Code-style ReAct loop), goal (autonomous auto-approve loop), and research (parallel-subagent fan-out + synthesis).
• Built-in tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, computer-control (macOS), and browser-session (Playwright, optional).
• Multi-channel by design: TUI, Telegram, HTTP, web, cron, and webhooks. One session can drive several surfaces at once.
• Voice input on any audio-capable channel through @moxxy/plugin-stt-whisper.
• An encrypted vault (AES-256-GCM at rest) so secrets in config are referenced as ${vault:KEY} and never written in plaintext.
• A long-term memory subsystem with a journal and vector recall. TF-IDF ships built-in. Swap to OpenAI embeddings via @moxxy/plugin-embeddings-openai.
• A permission resolver that gates every tool call and learns allow-always rules per tool.
• Opt-in capability isolation. Tools declare what they need and an isolator enforces it. inproc ships built-in. worker, subprocess, wasm, and Docker isolators drop in behind the same interface.
• A scheduler for cron expressions and one-shot ISO timestamps.
• A webhook listener with HMAC verification, header and JSON-path filters, and a cloudflared or ngrok tunnel helper.
• An OS service installer for launchd (macOS) and systemd (Linux), or a single serve --background process that runs every channel together.

Installation

npm install -g @moxxy/cli

Or run it without installing:

npx @moxxy/cli init

Requirements: Node.js 20.10 or later. An API key for a supported provider (Anthropic, OpenAI), or sign into ChatGPT via moxxy login openai-codex.

Quickstart

moxxy init      # interactive: choose provider, paste API key (stored in the vault)
moxxy           # launch the interactive TUI

One-shot from the command line:

moxxy -p "summarize the README in three bullets"

Resume a previous conversation:

moxxy resume

moxxy --help lists every command. moxxy <command> --help shows per-command details.

Commands

The CLI groups commands the same way moxxy --help does.

Setup

| Command | What it does | |---|---| | moxxy init | Interactive first-time setup. Picks a provider, captures the key, writes it into the vault. | | moxxy login <provider> | OAuth sign-in for providers that do not use API keys (for example openai-codex). | | moxxy login status | Show stored OAuth credentials. | | moxxy login logout <provider> | Remove stored OAuth credentials. | | moxxy doctor | Diagnose your install: provider readiness, vault unlock, missing optional dependencies. |

Run

| Command | What it does | |---|---| | moxxy | Default. Starts the Ink TUI. | | moxxy tui | Same as above, explicit. | | moxxy -p "…" (or --prompt) | One-shot prompt to stdout. | | moxxy resume [-s <id>] | Resume a persisted session. Interactive picker if no id. | | moxxy <channel> | Start a registered channel by name. | | moxxy channels | List registered channels and their subcommands. | | moxxy serve | Start every channel together with the scheduler and webhooks in one process. |

Manage

| Command | What it does | |---|---| | moxxy sessions list and delete | Inspect or remove persisted sessions. | | moxxy skills list, new, audit | Manage skill files across user, project, builtin, and plugin scopes. | | moxxy plugins list, reload, new | Manage the plugin host. reload picks up newly installed packages. | | moxxy mcp list, add, enable, disable, remove | Manage MCP servers in ~/.moxxy/mcp.json. | | moxxy perms list, add, remove | Inspect or edit the persisted permission rules. | | moxxy memory journal and recall | Read or query long-term memory. | | moxxy schedule add, list, remove | Time-driven prompts (cron or one-shot ISO). | | moxxy security audit, status, isolators | Inspect tool capability declarations and the active isolator. | | moxxy service install, logs, status, uninstall | Background OS services (launchd or systemd). | | moxxy self-update | Update bundled plugins, skills, and core safely. |

Flags

| Flag | What it does | |---|---| | --prompt, -p "…" | One-shot input. | | --model <id> | Override the default model for this invocation. | | --output-format <fmt> | text, json, or stream-json (one-shot output mode). | | --cwd <path> | Set the agent's working directory. | | --config <path> | Load a specific moxxy.config.ts. | | --no-color | Disable ANSI colors. | | -h, --help, -v, --version | Standard. |

Environment

| Variable | What it does | |---|---| | ANTHROPIC_API_KEY | Default Anthropic provider key. | | OPENAI_API_KEY | OpenAI provider key (also used by the openai embeddings plugin). | | MOXXY_VAULT_PASSPHRASE | Headless vault unlock when no OS keychain is available. | | MOXXY_FIXTURES | record or replay. Provider fixture mode used by tests. |

Channels

Run your agent through whichever surface fits the task.

| Channel | What it does | Command | |---|---|---| | TUI | Grok-style interactive terminal UI. | moxxy | | Telegram | Message the agent from anywhere. Voice notes get transcribed and run as turns. Pairs with a 6-digit code. | moxxy telegram | | HTTP | POST /v1/turn (JSON, SSE streaming) and POST /v1/turn/audio (raw bytes, iOS Shortcut friendly), bearer-token auth. | moxxy channels http | | Cron | Time-driven prompts. Cron expressions or one-shot ISO timestamps. | moxxy schedule add … | | Webhooks | External systems fire prompts on signed POST. HMAC plus bearer plus filter rules. | moxxy serve (auto-starts the listener) |

Services

Two ways to keep moxxy online 24/7.

Per-channel units, one process each so failures stay independent:

moxxy service install telegram     # launchd on macOS, systemd --user on Linux
moxxy service logs telegram         # tail the log

Or one process for everything, with a shared event log:

moxxy serve --background            # every channel plus the scheduler plus webhooks
moxxy serve --background --except http   # skip what you do not want
moxxy serve --status                # is it running?

Logs land in ~/.moxxy/services/<name>.log. The units survive reboots.

Configuration

moxxy.config.ts at your project root:

import { defineConfig } from '@moxxy/config';

export default defineConfig({
  provider: {
    name: 'anthropic',
    model: 'claude-sonnet-4-6',
    config: { apiKey: '${vault:ANTHROPIC_API_KEY}' },   // resolved from the vault
  },
  mode: 'default',
  plugins: {
    '@moxxy/plugin-browser': { enabled: false },        // disable a plugin (or use `moxxy plugins disable`)
  },
});

${vault:NAME} placeholders resolve on session start. The vault unlocks via OS keychain (keytar) with a passphrase fallback (MOXXY_VAULT_PASSPHRASE for headless boxes).

Docs

Full documentation lives at docs.moxxy.ai: concepts, recipes, plugin authoring, channel guides. The marketing site is at moxxy.ai.

Contributing

PRs welcome. The issue tracker and author guides live in the moxxy monorepo.

License

MIT. See the repository root for the full text.