@moxxy/cli 0.0.12 → 0.1.1

package/README.md

@@ -1,155 +1,321 @@
-# @moxxy/cli
+<p align="center">
+  <img src="https://moxxy.ai/logo-gradient.svg" alt="Moxxy" width="80" />
+</p>
 
-User-facing CLI for [Moxxy](https://github.com/webeferen/moxxy) agent orchestration.
+<h1 align="center">@moxxy/cli</h1>
 
-## Installation
+<p align="center">
+  <strong>CLI and full-screen TUI for the Moxxy agentic framework.</strong>
+</p>
 
-```bash
-npm install -g @moxxy/cli
-```
-
-## Quick Start
-
-```bash
-# Interactive setup — walks you through each config step
-moxxy config init
-
-# Or pass flags directly
-moxxy config init --sdk claude --github-token ghp_xxx
-
-# Add a repository to watch
-moxxy repo add owner/repo --events issues.opened,issues.labeled
-
-# Start orchestration
-moxxy start
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/@moxxy/cli"><img src="https://img.shields.io/npm/v/@moxxy/cli?color=cb3837&logo=npm&logoColor=white" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A522-5FA04E?logo=node.js&logoColor=white" alt="Node.js 22+">
+  <a href="https://github.com/moxxy-ai/moxxy"><img src="https://img.shields.io/badge/github-moxxy-181717?logo=github&logoColor=white" alt="GitHub"></a>
+  <a href="https://github.com/moxxy-ai/moxxy/blob/main/LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue" alt="License"></a>
+</p>
 
-## Commands
-
-### `moxxy config init`
-
-Initialize configuration. Launches an interactive wizard when called without flags.
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--sdk <provider>` | `molt` or `claude` | _(interactive)_ |
-| `--github-token <token>` | GitHub personal access token | _(interactive)_ |
-| `--gateway-url <url>` | Molt Gateway URL (molt only) | |
-| `--auth-token <token>` | Molt Gateway auth token | |
-| `--claude-api-key <key>` | Anthropic API key (claude only) | |
-| `--claude-model <model>` | Claude model | `claude-sonnet-4-5` |
-| `--claude-cli-path <path>` | Path to Claude CLI binary | `claude` |
-| `--webhook-secret <secret>` | GitHub webhook secret | |
-| `--webhook-port <port>` | Webhook server port | `3456` |
-| `--agent-id <id>` | Agent ID | |
-
-### `moxxy config set <key> <value>`
+---
 
-Set a config value using dot notation (e.g. `moxxy config set webhook.port 8080`).
+`@moxxy/cli` is the command-line interface for [Moxxy](https://github.com/moxxy-ai/moxxy) — a local-first framework for building, running, and orchestrating AI agents. It provides interactive wizards for every operation and a split-pane TUI for real-time agent interaction.
 
-### `moxxy config get <key>`
+## Requirements
 
-Read a config value using dot notation.
+- **Node.js** 22+
+- A running **Moxxy gateway** (the Rust backend — see [full setup](https://github.com/moxxy-ai/moxxy#getting-started))
 
-### `moxxy repo add <owner/repo>`
+## Install
 
-Add a repository to watch.
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--branch <branch>` | Default branch | `main` |
-| `--events <events>` | Comma-separated events | `issues.opened,issues.labeled` |
+```bash
+npm install --global @moxxy/cli
+```
 
-### `moxxy repo list`
+Or run from source:
 
-List all configured repositories.
+```bash
+cd apps/moxxy-cli
+npm install
+node --import tsx src/cli.js
+```
 
-### `moxxy repo remove <owner/repo>`
+## Quick Start
 
-Remove a repository from the watch list.
+```bash
+# First-time setup (creates token, configures provider)
+moxxy init
 
-### `moxxy start`
+# Open the full-screen chat interface
+moxxy tui
+```
 
-Start the orchestration server. Connects to the configured SDK, initializes the agent supervisor, and starts the webhook server to listen for GitHub events on watched repositories.
+Every command launches an **interactive wizard** when run without flags — just type the command and follow the prompts.
 
-### `moxxy status`
+## Commands
 
-Display current configuration: SDK provider, GitHub token status, webhook settings, watched repositories, and agent configuration.
+```
+moxxy                                               Interactive menu
+moxxy init                                          First-time setup wizard
+moxxy doctor                                        Diagnose installation
+moxxy update [--check] [--force] [--json]           Check for and install updates
+moxxy update --rollback                             Restore previous gateway version
+moxxy uninstall                                     Remove all Moxxy data
+
+moxxy tui [--agent <id>]                            Full-screen chat interface
+moxxy chat [--agent <id>]                           Alias for tui
+
+moxxy gateway start|stop|restart|status|logs
+
+moxxy auth token create [--scopes <s>] [--ttl <n>] [--json]
+moxxy auth token list [--json]
+moxxy auth token revoke <id>
+
+moxxy provider list
+moxxy provider install --id <provider-id>
+moxxy provider login --id <id> --method browser|headless
+
+moxxy agent create --provider <p> --model <m> --workspace <w> [--json]
+moxxy agent run --id <id> --task "task" [--json]
+moxxy agent stop --id <id>
+moxxy agent status --id <id> [--json]
+moxxy agent update --id <id> [--model <m>] [--temperature <n>]
+moxxy agent delete --id <id>
+
+moxxy skill create --agent <id> --content <c>
+moxxy skill list --agent <id>
+moxxy skill remove --agent <id> --skill <id>
+
+moxxy template list
+moxxy template get <slug>
+moxxy template create --content <c>
+moxxy template update --slug <slug> --content <c>
+moxxy template remove <slug>
+moxxy template assign --agent <id> --template <slug>
+
+moxxy vault add --key <k> --backend <b>
+moxxy vault grant --agent <id> --secret <id>
+moxxy vault revoke --id <id>
+moxxy vault list
+
+moxxy heartbeat set --agent <id> --interval <n> [--action_type <t>]
+moxxy heartbeat list --agent <id>
+moxxy heartbeat disable --agent <id> --id <id>
+
+moxxy channel create
+moxxy channel list
+moxxy channel pair --code <code> --agent <id>
+moxxy channel delete <id>
+moxxy channel bindings <id>
+moxxy channel unbind <channel-id> <binding-id>
+
+moxxy mcp list --agent <name>
+moxxy mcp add --agent <name> --id <id> --transport stdio --command <cmd> [--args ...]
+moxxy mcp add --agent <name> --id <id> --transport sse --url <url>
+moxxy mcp remove --agent <name> --id <id>
+moxxy mcp test --agent <name> --id <id>
+
+moxxy plugin list                                   List installed plugins
+moxxy plugin install <package>                       Install a plugin
+moxxy plugin start <name>                            Start a plugin
+moxxy plugin stop <name>                             Stop a plugin
+moxxy plugin restart <name>                          Restart a plugin
+moxxy plugin uninstall <name>                        Remove a plugin
+moxxy plugin logs <name>                             Tail plugin logs
+
+moxxy events tail [--agent <id>] [--run <id>] [--json]
+```
 
-## Connecting to GitHub
+Add `--json` to most commands for machine-readable output.
 
-Moxxy uses standard GitHub repository webhooks (no GitHub App required). You need a **GitHub Personal Access Token** and a publicly reachable URL for your webhook server.
+## TUI
 
-### 1. Generate a webhook secret
+The built-in terminal UI provides a split-pane interface with real-time SSE event streaming:
 
-```bash
-openssl rand -hex 32
 ```
-
-Save this value — you'll use it in both Moxxy config and GitHub.
-
-### 2. Initialize Moxxy
-
-```bash
-moxxy config init
+┌─────────────────────────────────┬──────────────────────┐
+│  Chat                           │  Agent Info          │
+│                                 │  ID: 019cac...       │
+│  > You: Refactor auth module    │  Provider: anthropic │
+│                                 │  Model: claude-4     │
+│  Assistant: Analyzing...        │  Status: ● running   │
+│                                 │                      │
+│  [skill.invoked] fs.read        │  ── Usage ──         │
+│  [skill.completed] fs.read      │  Tokens: 12,450      │
+│                                 │  Events: 34          │
+├─────────────────────────────────┴──────────────────────┤
+│  > Type a task...                            Ctrl+C    │
+└────────────────────────────────────────────────────────┘
 ```
 
-The interactive wizard will ask for your SDK provider, GitHub PAT, webhook secret, and port. Or pass flags directly:
+**Slash commands** inside the TUI:
+
+| Command | Description |
+|---|---|
+| `/quit`, `/exit` | Exit the TUI |
+| `/stop` | Stop the running agent |
+| `/new`, `/reset` | Reset session and start fresh |
+| `/clear` | Clear chat history |
+| `/help` | Show available commands |
+| `/status` | Show agent status |
+| `/model` | Open interactive model picker |
+| `/vault` | Open vault actions |
+| `/mcp` | Open MCP actions |
+| `/template` | Open template actions |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `MOXXY_API_URL` | `http://localhost:3000` | Gateway base URL |
+| `MOXXY_TOKEN` | — | API bearer token |
+
+## Supported Providers
+
+The CLI includes a built-in provider catalog:
+
+| Provider | Env Var | Auth |
+|---|---|---|
+| Anthropic | `ANTHROPIC_API_KEY` | API key, OAuth |
+| OpenAI | `OPENAI_API_KEY` | API key |
+| OpenAI Codex | `OPENAI_CODEX_SECRET_KEY` | OAuth (browser/headless) |
+| Ollama | — | Local OpenAI-compatible endpoint, no auth |
+| xAI | `XAI_API_KEY` | API key |
+| Google Gemini | `GOOGLE_API_KEY` | API key |
+| DeepSeek | `DEEPSEEK_API_KEY` | API key |
+| ZAI | `ZAI_API_KEY` | API key |
+| ZAI Plan | `ZAI_API_KEY` | API key |
+| Claude Code CLI | — | Claude Code binary |
+| Custom | Any | OpenAI-compatible endpoint |
+
+## Plugins
+
+Plugins are npm packages that extend Moxxy with additional functionality — web dashboards, virtual offices, custom integrations, and more. Each plugin runs as a standalone process that connects to the gateway via the REST API and SSE events.
+
+### Built-in plugins
+
+| Plugin | Package | Description |
+|---|---|---|
+| Web Dashboard | `@moxxy/web-plugin` | Browser-based dashboard on port 17900 |
+| Virtual Office | `@moxxy/virtual-office-plugin` | Virtual office environment on port 5174 |
 
 ```bash
-moxxy config init \
-  --sdk claude \
-  --github-token ghp_xxx \
-  --webhook-secret your-secret \
-  --webhook-port 3456
-```
-
-### 3. Expose the webhook server
+# Install and start the web dashboard
+moxxy plugin install @moxxy/web-plugin
+moxxy plugin start @moxxy/web-plugin
 
-Moxxy listens on `localhost:3456` by default. For GitHub to reach it, expose it with a tunnel:
-
-```bash
-ngrok http 3456
+# Or use the interactive menu
+moxxy plugin
 ```
 
-This gives you a public URL like `https://abc123.ngrok-free.app`.
-
-### 4. Add a webhook on GitHub
-
-Go to your repository **Settings > Webhooks > Add webhook**:
+### Creating a custom plugin
+
+A Moxxy plugin is any npm package that declares a `moxxy` section and a `plugin:start` script in its `package.json`:
+
+```json
+{
+  "name": "my-moxxy-dashboard",
+  "version": "1.0.0",
+  "moxxy": {
+    "type": "plugin",
+    "displayName": "My Dashboard",
+    "description": "Custom monitoring dashboard for Moxxy agents",
+    "port": 4000
+  },
+  "scripts": {
+    "plugin:start": "node src/server.js",
+    "plugin:stop": "echo 'shutting down'",
+    "plugin:install": "npm run build",
+    "plugin:uninstall": "rm -rf dist"
+  }
+}
+```
 
-| Field | Value |
-|-------|-------|
-| Payload URL | `https://<your-ngrok-url>/webhook/github` |
-| Content type | `application/json` |
-| Secret | the same secret from step 1 |
-| Events | select "Let me select individual events" > check **Issues** |
+**Required fields:**
+
+- `moxxy.type` — must be `"plugin"`
+- `scripts["plugin:start"]` — the command that starts your plugin
+
+**Optional fields:**
+
+- `moxxy.displayName` — friendly name shown in the CLI menu
+- `moxxy.description` — short description
+- `moxxy.port` — default port the plugin listens on
+- `scripts["plugin:stop"]` — graceful shutdown hook (run before SIGTERM)
+- `scripts["plugin:install"]` — post-install setup (e.g. build step)
+- `scripts["plugin:uninstall"]` — cleanup hook before removal
+
+### Environment variables
+
+When started, your plugin receives these environment variables:
+
+| Variable | Description |
+|---|---|
+| `MOXXY_API_URL` | Gateway base URL (e.g. `http://localhost:3000`) |
+| `MOXXY_TOKEN` | API bearer token for gateway access |
+| `MOXXY_PLUGIN_NAME` | The plugin's own package name |
+| `MOXXY_PLUGIN_PORT` | Allocated port from `moxxy.port` |
+| `MOXXY_HOME` | Moxxy home directory (`~/.moxxy`) |
+| `PORT` | Same as `MOXXY_PLUGIN_PORT` (convenience) |
+
+### Example: minimal plugin
+
+```js
+// src/server.js
+import http from 'node:http';
+
+const PORT = process.env.PORT || 4000;
+const API_URL = process.env.MOXXY_API_URL;
+const TOKEN = process.env.MOXXY_TOKEN;
+
+const server = http.createServer(async (req, res) => {
+  if (req.url === '/') {
+    // Fetch agents from the gateway
+    const resp = await fetch(`${API_URL}/v1/agents`, {
+      headers: { Authorization: `Bearer ${TOKEN}` },
+    });
+    const agents = await resp.json();
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(`
+      <h1>Moxxy Agents</h1>
+      <ul>${agents.map(a => `<li>${a.name} [${a.status}]</li>`).join('')}</ul>
+    `);
+    return;
+  }
+  res.writeHead(404).end('Not found');
+});
+
+server.listen(PORT, () => console.log(`Dashboard running on http://localhost:${PORT}`));
+```
 
-### 5. Add the repo and start
+Publish to npm, then install in Moxxy:
 
 ```bash
-moxxy repo add owner/repo
-moxxy start
+moxxy plugin install my-moxxy-dashboard
+moxxy plugin start my-moxxy-dashboard
 ```
 
-Open an issue on the repo to verify Moxxy picks it up.
+### Plugin lifecycle scripts
 
-### Webhook details
+| Script | When it runs |
+|---|---|
+| `plugin:install` | After `npm install`, before first use (build steps, etc.) |
+| `plugin:start` | When the user runs `moxxy plugin start <name>` |
+| `plugin:stop` | Before SIGTERM when the user runs `moxxy plugin stop <name>` |
+| `plugin:uninstall` | Before removal when the user runs `moxxy plugin uninstall <name>` |
 
-- **Path**: `/webhook/github` (fixed)
-- **Signature verification**: HMAC-SHA256 via `X-Hub-Signature-256` header. Optional but recommended — if no secret is configured, all requests are accepted.
-- **Supported events**: `issues` (actions: `opened`, `labeled`)
+## About Moxxy
 
-## Programmatic Usage
+Moxxy is a local-first agentic framework with a Rust core and Node.js CLI. It provides:
 
-```typescript
-import { createProgram, ConfigManager } from '@moxxy/cli';
+- **80+ built-in primitives** — filesystem, git, shell, HTTP, browsing, memory, webhooks, vault, MCP, hive orchestration, allowlists, and more
+- **Skill-based agents** — Markdown skills with YAML frontmatter that define capabilities and permission boundaries
+- **Multi-agent orchestration** — hive swarms with task boards, proposals, voting, and signal-based coordination
+- **Strong isolation** — sandboxed workspaces, command allowlists, domain-gated networking, OS keychain secrets
+- **MCP support** — connect agents to Model Context Protocol servers (stdio and SSE transports)
+- **Real-time observability** — SSE event streaming with automatic secret redaction
 
-const manager = new ConfigManager();
-await manager.load();
-console.log(manager.get('sdk'));
-```
+For the full project, architecture, and development guide, see the [main repository](https://github.com/moxxy-ai/moxxy).
 
 ## License
 
-MIT
+Dual-licensed under [MIT](https://github.com/moxxy-ai/moxxy/blob/main/LICENSE-MIT) or [Apache 2.0](https://github.com/moxxy-ai/moxxy/blob/main/LICENSE-APACHE) at your option.

package/bin/moxxy

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Resolve symlinks (npm link creates symlinks) to find the real script location
+SOURCE="$0"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [ "${SOURCE%${SOURCE#?}}" != "/" ] && SOURCE="$DIR/$SOURCE"
+done
+CLI_DIR="$(cd "$(dirname "$SOURCE")/.." && pwd)"
+exec node --import "$CLI_DIR/node_modules/tsx/dist/esm/index.mjs" "$CLI_DIR/src/cli.js" "$@"

package/package.json

@@ -1,71 +1,54 @@
 {
   "name": "@moxxy/cli",
-  "version": "0.0.12",
-  "description": "User-facing CLI for Moxxy agent orchestration",
+  "version": "0.1.1",
+  "description": "CLI for the Moxxy agentic framework — manage agents, skills, plugins, channels, and vaults from the terminal",
+  "type": "module",
   "license": "MIT",
+  "author": "Moxxy AI <hello@moxxy.ai> (https://moxxy.ai)",
   "repository": {
     "type": "git",
-    "url": "https://github.com/webeferen/moxxy.git",
-    "directory": "packages/cli"
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "apps/moxxy-cli"
+  },
+  "homepage": "https://github.com/moxxy-ai/moxxy/tree/main/apps/moxxy-cli#readme",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
   },
-  "homepage": "https://github.com/webeferen/moxxy/tree/main/packages/cli",
-  "bugs": "https://github.com/webeferen/moxxy/issues",
   "keywords": [
     "moxxy",
-    "cli",
+    "ai",
     "agent",
-    "orchestration"
+    "agentic",
+    "framework",
+    "cli",
+    "llm",
+    "automation",
+    "orchestration",
+    "skills",
+    "plugins",
+    "mcp"
   ],
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=20"
   },
   "files": [
-    "dist",
-    "bin",
-    "README.md"
+    "bin/",
+    "src/"
   ],
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
   "bin": {
-    "moxxy": "./bin/moxxy.js"
+    "moxxy": "./bin/moxxy"
   },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
+  "scripts": {
+    "dev": "node --import tsx --watch src/cli.js",
+    "test": "node --import tsx --test test/cli.test.js test/tui.test.js test/update.test.js test/plugin.test.js"
   },
   "dependencies": {
-    "commander": "^13.0.0",
-    "chalk": "^4.1.2",
-    "ora": "^5.4.1",
-    "prompts": "^2.4.2",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.13",
-    "@types/prompts": "^2.4.9",
-    "@types/node": "^22.0.0",
-    "tsup": "^8.0.1",
-    "typescript": "^5.7.0",
-    "vitest": "^2.1.0",
-    "@moxxy/types": "1.0.0",
-    "@moxxy/claude": "0.1.0",
-    "@moxxy/integration-base": "1.0.0",
-    "@moxxy/agents": "1.0.0",
-    "@moxxy/integration-github": "1.0.0",
-    "@moxxy/molt": "1.0.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "clean": "rm -rf dist *.tsbuildinfo",
-    "start": "node bin/moxxy.js"
+    "@clack/prompts": "^1.0.1",
+    "@inkjs/ui": "^2.0.0",
+    "chalk": "^5.6.2",
+    "ink": "^6.0.0",
+    "marked": "^15.0.0",
+    "react": "^19.0.0",
+    "tsx": "^4.21.0"
   }
-}
+}