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, checks the Git identity used by Autopilot, adds repositories, applies a dashboard preset, and can create initial schedules and command preapprovals. If the global identity is incomplete, setup warns and offers to write user.name, user.email, and user.useConfigOnly=true. Complete GIT_AUTHOR_* and GIT_COMMITTER_* overrides are accepted only when persisted in the selected runtime-home .env.

Model setup also offers an optional model and reasoning profile for the shared explore subagent. It defaults to the display-assistant model. For lower delegation latency and cost, setup recommends a fast profile such as OpenAI Luna with high reasoning or OpenAI Terra with medium reasoning.

Provider authentication

neondeck auth login openai-codex
neondeck auth status openai-codex
neondeck --json auth status openai-codex
neondeck auth logout openai-codex

ChatGPT subscription login supports a local browser callback or a device code. Neondeck stores and refreshes the OAuth credentials in its local app database. Restart Neondeck after standalone CLI login or logout so the running process picks up the new credential state. Status reports missing, valid, refresh-needed, or error, along with whether credentials are stored and currently usable. Expiry and the latest refresh error are included when available.

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 db backup
neondeck db backups
neondeck db restore <backup-name>
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. db backup creates a consistent manual snapshot; db backups lists the recognized snapshots newest first; and db restore validates a named snapshot, safeguards the current database, and restores it. Stop Neondeck before restoring. 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 --browser "/path/to/chromium"
neondeck open xeneon --browser "/path/to/chromium"

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. Without an installed service, it keeps the server attached to the current terminal until Ctrl-C. An installed service remains managed by service start and service stop. Named window profiles come from runtime-home dashboard.json under windows; new runtime homes include sidebar and xeneon. Width/height and x/y must be supplied in pairs, and CLI flags override profile values for one launch. By default, Neondeck delegates to the OS default browser. Window geometry and kiosk mode apply only when --browser <path> selects a Chromium-family executable for app-mode 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, semantic autonomous delivery, 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 an app-owned service or a bounded Flue agent submission when model reasoning is required.

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 chosen from the chat input's slash-command suggestions. /review-pr prepares a local briefing and Neon-origin draft review comments for a human reviewer; it does not submit a GitHub review. /fix-ci queues a bounded app-owned CI fix operation 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.