Root CLI Subcommands

Start the Weasley Podex server in the foreground. The server must be running before chat, dispatch, browser, and most other commands can operate.

weasley-podex serve [--port <N>] [--no-open] [--lan] [--remote]

Examples

# Start with defaults (port 3457, auto-opens browser)
weasley-podex serve

# Custom port, no browser
weasley-podex serve --port 3458 --no-open

# LAN mode for local network access
weasley-podex serve --lan --port 3460

# Use a separate data directory
weasley-podex --home ~/.weasley/podex-work serve --port 3458

Multi-instance manager. Start the dashboard server, list/start/stop instances, manage persistent services, and perform L2 cross-instance memory federation searches.

weasley-podex dashboard <command> [options] [--json]

Examples

# Start the dashboard
weasley-podex dashboard serve

# List online instances as JSON
weasley-podex dashboard ls --json | jq '.[] | select(.status == "online")'

# Start a new instance on port 3458
weasley-podex dashboard start 3458 --home ~/.weasley/podex-work

# Stop an instance
weasley-podex dashboard stop 3457

# Cross-instance memory search
weasley-podex dashboard memory search "JWT authentication"

# List all memory instances
weasley-podex dashboard memory instances

# Register for persistent auto-start
weasley-podex dashboard perm 3458 --home ~/.weasley/podex-work

Check if the Weasley Podex server is running by pinging the API. Optionally check the dashboard server too.

weasley-podex status [--port <N>] [--json] [--dashboard]

Exit code 0 = server running, 1 = server not running or error.

Examples

# Quick health check
weasley-podex status

# JSON output for scripting
weasley-podex status --json
# → {"status":"running","port":"3457","cli":"claude"}

# Check both server and dashboard
weasley-podex status --dashboard

# Check a specific port
weasley-podex status --port 3458

Interactive setup wizard for first-time configuration. Creates ~/.weasley/podex/settings.json, configures the default CLI backend, messaging channels, and skills directory.

weasley-podex init [options]

Examples

# Interactive wizard (recommended for first run)
weasley-podex init

# Non-interactive with defaults
weasley-podex init --non-interactive --cli claude

# Re-initialize with force
weasley-podex init --force --cli gemini --channel telegram

# Dry run to see what would be created
weasley-podex init --dry-run

Diagnose installation and configuration health. Checks Node.js version, CLI binary resolution, settings file validity, MCP server connectivity, employee CLI availability, and port availability.

weasley-podex doctor [--json] [--fix] [--tcc] [--prime]

Examples

# Run diagnostics
weasley-podex doctor

# Machine-readable output
weasley-podex doctor --json

# Auto-fix detected issues
weasley-podex doctor --fix

# Check macOS accessibility permissions
weasley-podex doctor --tcc

Factory reset: performs MCP sync, skill reset, employee reset, and session clear. Prompts for confirmation unless --yes is passed. Requires a running server.

weasley-podex reset [--yes] [--port <N>]

Examples

# Reset with confirmation prompt
weasley-podex reset

# Skip confirmation (scripting)
weasley-podex reset --yes

# Reset a specific instance
weasley-podex reset --port 3458 --yes

Interactive terminal REPL. Connects to the running server through the SSE-first TUI channel, with legacy WebSocket fallback for older servers. Supports a rich TUI mode with persistent footer, a raw JSON protocol mode for UI integration, and a minimal plain readline mode.

weasley-podex chat [--port <N>] [--raw] [--simple]

Examples

# Default rich TUI
weasley-podex chat

# Simple mode (works in dumb terminals)
weasley-podex chat --simple

# Connect to a different instance
weasley-podex chat --port 3458

# Raw JSON mode for piping
weasley-podex chat --raw

Send a task to an employee agent. The employee runs asynchronously via the server API and returns results via stdout. Pipe-compatible for scripting workflows. Requires WEASLEY_PODEX_BOSS_TOKEN (inherited from the server process).

weasley-podex dispatch --agent <name> --task <text> [--json] [--port <N>]

Examples

# Dispatch a frontend task
weasley-podex dispatch --agent "Frontend" --task "Fix CSS bug in the header component"

# Dispatch a backend task
weasley-podex dispatch --agent "Backend" --task "Add rate limiting to /api/chat endpoint"

# JSON output for piping
weasley-podex dispatch --agent "Data" --task "Optimize the slow query in reports" --json

Employee management utilities. Currently supports resetting employees to the default 5 profiles (Frontend, Backend, Data, Docs, QA).

weasley-podex employee <subcommand> [--port <N>]

Examples

# Reset all employees to defaults
weasley-podex employee reset

# Reset on a specific instance
weasley-podex employee reset --port 3458

PABCD state machine transitions. Drives the workflow through Interview, Planning, Audit, Build, Check, and Done phases. Calls the running server's API so SSE-first event updates reach connected clients in real time.

weasley-podex orchestrate <phase> [--force] [--json] [--port <N>]

Valid transitions: IDLE → I → P → A → B → C → D → IDLE. Interview is optional: IDLE → P is also valid.

Examples

# Start planning phase
weasley-podex orchestrate P

# Force transition (skip validation)
weasley-podex orchestrate B --force

# Check current state
weasley-podex orchestrate status

# Reset to IDLE
weasley-podex orchestrate reset

# JSON output
weasley-podex orchestrate status --json

Persistent goal lifecycle management. Set objectives, track progress with checkpoints, and manage goal state (pause, resume, cancel, complete). Goals survive across sessions and server restarts.

weasley-podex goal <subcommand> [args...] [--port <N>]

Examples

# Set a new goal
weasley-podex goal set "Implement keyboard shortcuts for the editor"

# Check current goal
weasley-podex goal status

# Add a progress checkpoint
weasley-podex goal update "K0: shortcut registry done, K1: in progress"

# Mark complete
weasley-podex goal done "All phases complete, PR merged"

# View past goals
weasley-podex goal history 5

# Pause and resume
weasley-podex goal pause
weasley-podex goal resume

# Cancel with reason
weasley-podex goal cancel "Deprioritized in favor of auth refactor"

Persistent memory store CLI. Search, read, save, and list memory files. Memory is stored as markdown files in ~/.weasley/podex/memory/ and indexed for semantic search.

weasley-podex memory <subcommand> [args...]

Examples

# Search memory
weasley-podex memory search "JWT authentication patterns"

# Read a specific file
weasley-podex memory read structured/profile.md

# Save a new memory entry
weasley-podex memory save structured/profile.md "- User prefers concise Korean summaries"

# Save an episode log
weasley-podex memory save structured/episodes/live/2026-05-29.md "## 14:30\n- Completed CLI docs page"

# List all files
weasley-podex memory list

Chrome browser control via CDP (Chrome DevTools Protocol). Open pages, take screenshots, click elements, type text, manage tabs, and perform web AI-powered browsing. Requires the server to be running.

weasley-podex browser <subcommand> [args...]

Examples

# Check browser status
weasley-podex browser status

# Open a page and take a screenshot
weasley-podex browser open https://example.com
weasley-podex browser screenshot

# Get page snapshot for element refs
weasley-podex browser snapshot

# Click and type using refs
weasley-podex browser click ref:42
weasley-podex browser type ref:15 "search query"

# Adaptive fetch
weasley-podex browser fetch https://example.com/api/data

Skill management: list installed skills, install from reference/Codex/GitHub, remove skills, and view skill details. Skills are injected into the agent's system prompt.

weasley-podex skill [subcommand] [name...]

Examples

# List installed skills
weasley-podex skill

# Install a skill
weasley-podex skill install cloudflare
weasley-podex skill install docker kubernetes terraform

# Remove a skill
weasley-podex skill remove cloudflare

# View skill details
weasley-podex skill info dev-frontend

# Reset to defaults
weasley-podex skill reset

MCP (Model Context Protocol) server management. Install npm/PyPI MCP packages, sync configuration to all 6 CLI backends, list registered servers, or reset to defaults.

weasley-podex mcp [subcommand] [package]

Package ecosystem is auto-detected: @scope/name is npm; mcp-server-* is PyPI. Use --pypi or --npm to override.

Examples

# List all MCP servers
weasley-podex mcp

# Install an npm MCP package
weasley-podex mcp install @modelcontextprotocol/server-filesystem

# Install a PyPI MCP package
weasley-podex mcp install mcp-server-git

# Sync configuration to all CLIs
weasley-podex mcp sync

# Reset to default MCP servers
weasley-podex mcp reset --force

Dashboard connector CLI -- a unified entry point for the kanban board, notes, reminders, and audit log. Provides direct CLI access to dashboard features without the web UI.

weasley-podex connector <surface> <subcommand> [options]

Examples

# Add a kanban task
weasley-podex connector board add --title "Implement auth flow" --lane backlog

# Move task to done
weasley-podex connector board update task-id-123 --lane done

# List board tasks
weasley-podex connector board list --json

# Write a note
weasley-podex connector notes write --path "meeting/standup.md" --body "# Standup Notes\n- Auth PR merged"

# List notes
weasley-podex connector notes list

# Add a reminder
weasley-podex connector reminders add --title "Review PR #42" --priority high --due 2026-06-01

Priority-based reminders with Eisenhower-style categorization. Shortcut for weasley-podex connector reminders.

weasley-podex reminders <subcommand> [options]

Examples

# List reminders
weasley-podex reminders list

# Add a reminder
weasley-podex reminders add "Review PR #42" --priority high --due 2026-06-01

# Add with notes
weasley-podex reminders add --title "Deploy staging" --notes "After QA sign-off" --priority normal

# Mark done
weasley-podex reminders done reminder-id-abc

# JSON output
weasley-podex reminders list --json

Manage project workspace directories. Set which directories the agent should consider as active project roots. Changes are applied via the server API and persist across sessions.

weasley-podex project <subcommand> [paths...]

Examples

# Set project directories
weasley-podex project set ~/Dev/frontend, ~/Dev/backend

# Set a single absolute path
weasley-podex project set /Users/example/projects/my-app

# List current directories
weasley-podex project list

# Clear all
weasley-podex project reset

Cross-platform auto-start management. Detects the OS and installs the server as a background daemon (launchd on macOS, systemd on Linux, Docker entrypoint in containers). One-step install + start.

weasley-podex service [subcommand] [--port <N>] [--backend <type>]

Examples

# One-step install + start (auto-detects OS)
weasley-podex service

# Custom port
weasley-podex service --port 3458

# Check service status
weasley-podex service status

# View logs
weasley-podex service logs

# Remove service
weasley-podex service unset

# Force a specific backend
weasley-podex service --backend systemd --port 3457

Create an independent agent instance by cloning the current configuration. Copies config and skills, creates a fresh database, and regenerates AGENTS.md. Useful for running multiple isolated agents.

weasley-podex clone <target-dir> [--from <source>] [--with-memory] [--link-ref]

Examples

# Clone to a new directory
weasley-podex clone ~/.weasley/podex-work

# Clone with memory
weasley-podex clone ~/.weasley/podex-research --with-memory

# Clone from a specific source
weasley-podex clone ~/.weasley/podex-staging --from ~/.weasley/podex-prod

# Symlink reference skills to save space
weasley-podex clone ~/.weasley/podex-dev --link-ref

macOS-specific LaunchAgent management (deprecated -- use weasley-podex service instead). Manages plist files for auto-start on login. Retained for backward compatibility.

weasley-podex launchd [subcommand] [--port <N>]

Examples

# One-step install + start
weasley-podex launchd

# Custom port
weasley-podex launchd --port 3458

# Check status
weasley-podex launchd status

# Remove
weasley-podex launchd unset

# Cleanup legacy plists
weasley-podex launchd cleanup