CLI

The CLI is the setup and command-and-control surface for neondeck. It also reserves the future OpenTUI launch path so the terminal client can reuse the same backend runtime.

Global options

neondeck --home ~/.config/neondeck status
neondeck --json status

Use --home to isolate a runtime home for testing. Use --json for machine-readable output where supported.

Initialize

neondeck init
neondeck init --home .neondeck-test

The init wizard creates runtime files, writes runtime-home secrets, tunes SOUL.md, configures models and provider references, adds repositories, applies a dashboard preset, and can create initial schedules and command preapprovals.

Status

neondeck status

Status reports runtime readiness, active home paths, model/provider config, credential presence, repo counts, skills, watches, and setup items that need attention.

Database

neondeck db status
neondeck --json db status

Database status reads the Neondeck app database migration journal, shipped migration head, pending entries, unknown newer entries, hash mismatches, and latest pre-migration backup path. There is no manual migrate command; migrations apply automatically before app code opens data/neondeck.db.

Serve, service, and open

neondeck serve --port 3583
neondeck service install
neondeck service status
neondeck service stop
neondeck service start
neondeck service uninstall
neondeck open
neondeck open sidebar
neondeck open xeneon --kiosk

serve starts the production server in the foreground. It expects the packaged dist/server.mjs entry; in a source checkout, run npm run build:server first or use npm run dev for the fast development loop. service install creates a login service on macOS launchd or Linux systemd user units. Windows users should run neondeck serve directly for now. Service status reports installation state, running pid when available, health, port, log path, and stale embedded Node or service entry paths.

open ensures the server is ready and opens the dashboard. Named window profiles come from runtime-home dashboard.json under windows. Width/height and x/y must be configured in pairs; CLI flags override profile values for one launch.

Repositories

neondeck repo add ~/dev/neondeck \
  --github-owner pandemicsyn \
  --github-name neondeck

neondeck repo list
neondeck repo diff neondeck --base main
neondeck repo diff neondeck --base main --patch
neondeck edit-events

Repositories should be local git checkouts when you want local status, dev doctor diagnostics, and command execution against the repo. Repo diffs read bounded metadata by default; --patch includes bounded patch text. Edit events expose the recent repo-edit audit trail.

Watches

neondeck watch-pr pandemicsyn/neondeck#521
neondeck watch-pr https://github.com/pandemicsyn/neondeck/pull/521
neondeck watch-pr pandemicsyn/neondeck#521 \
  --mode prepare-only \
  --process-existing \
  --confirm-autopilot

PR watches persist in SQLite and poll GitHub for meaningful review, commit, merge, and check changes. --process-existing handles current actionable feedback instead of baselining it. Any initial mode above notify-only, and every later increase in authority, requires explicit confirmation. See the Autopilot guide for modes, review, safe push, and recovery behavior.

External agent handoff

neondeck register-pr pandemicsyn/neondeck#521 \
  --from codex \
  --note "adds retry logic" \
  --json

neondeck note "Finished local cleanup without a PR." \
  --from claude-code \
  --repo neondeck \
  --level ready \
  --json

Handoff commands let same-host tools such as Claude Code, Codex, Kilo, and git hooks register work with Neon. They create attributed PR watches and notifications; they do not grant execution, approval, push, provider, or remote ingest powers. register-pr --review is default-off per command and also respects handoff.allowExternalReviewQueue in runtime-home config.json.

Scheduled tasks

Scheduled tasks are created with typed local API actions. The backend scheduler persists their validated trigger and dispatches each due occurrence through a bounded Flue workflow.

Neon slash commands

/repo-status [repo-id]
/review-queue
/review-pr <repo#number|owner/repo#number|url>
/fix-ci [repo#number|owner/repo#number]
/explain-ci [--report] [repo#number|owner/repo#number]
/summarize-pr [repo#number|owner/repo#number]
/draft-pr-description [repo-id|owner/repo]
/prepare-pr [repo-id|owner/repo]
/review-local [repo-id|owner/repo]
/briefing
/reasoning [off|minimal|low|medium|high|xhigh]
/memory ...
/watch-pr <repo#number|owner/repo#number|url>
/dev-doctor

Slash commands can be typed in chat, launched from dashboard buttons, or invoked through the command-run Flue workflow. /review-pr prepares local reports and Neon-origin draft review comments for a human reviewer; it does not submit a GitHub review. /fix-ci queues a bounded CI fix workflow and routes any resulting code change back through prepared-diff review. /explain-ci --report writes the CI dossier without starting a fix attempt. In the dashboard chat, /briefing persists a local snapshot and streams a normal assistant response; it does not render the legacy deterministic result card.

Reports and scheduled tasks

GET /api/reports?kind=docs-drift
GET /api/scheduled-tasks
GET /api/briefings
GET /api/briefings/runs/:id
PUT /api/briefings/profile
POST /api/briefings/run
POST /api/briefings/session/rotate
POST /api/scheduled-tasks/briefings
POST /api/scheduled-tasks/instructions
POST /api/scheduled-tasks/:id/pause
POST /api/scheduled-tasks/:id/resume

Reports and scheduled tasks are primarily dashboard/API surfaces rather than top-level CLI subcommands in this slice. Reports are local HTML artifacts opened from the Reports panel or /reports/:id. Scheduled tasks use typed local API routes and task actions.

MCP servers

neondeck mcp list
neondeck mcp status [id]
neondeck mcp add linear --url https://mcp.linear.app/mcp --oauth
neondeck mcp enable linear
neondeck mcp disable linear
neondeck mcp login linear
neondeck mcp tools linear
neondeck mcp approvals
neondeck mcp approvals --resolve <id> --approve
neondeck mcp audit
neondeck mcp logout linear --confirm
neondeck mcp remove linear --confirm

MCP config lives in runtime-home mcp.json. Stdio servers, header-authenticated servers, and auto-approval policy should be managed from user-owned CLI, local API, or config surfaces.

Learning

neondeck learning status
neondeck learning reviews
neondeck learning candidates --status proposed
neondeck learning events
neondeck learning approve <candidate-id>
neondeck learning reject <candidate-id>
neondeck learning restore-skill-patch <candidate-id>

Learning commands inspect the same review, candidate, and audit state as GET /api/learning/state. Approve/reject commands decide memory or skill candidates through typed actions. Restore only works for applied skill patches whose current file still matches the applied audit hash.

Diagnostics

neondeck doctor

Doctor runs local readiness checks for runtime state, configured repositories, credentials, services, and development prerequisites.

TUI

neondeck tui

The command is reserved for the future OpenTUI client. The TUI should reuse backend APIs and event streams rather than growing a second agent runtime.