neon-pilot-admin-cli

name	neon-pilot-admin-cli
description	Use the unified Neon Pilot CLI/control plane for self-administration, delegated agent control, conversations, workspace/sidebar state, runs, automations, extensions, settings, and extension-contributed administration surfaces.

Neon Pilot CLI

Use the unified Neon Pilot command surface instead of direct runtime-file edits, standalone model tools, or MCP. External/other agents use the public neon-pilot CLI. Internal Neon Pilot agents use the canonical neon_pilot tool when available. These are dual interfaces over the same control-plane command semantics, but the public CLI should stay human/task-oriented.

Workflow

1. Choose commands by intent before inspecting contracts:

   neon-pilot ask "Summarize this repo"                         # one-off agent work
   neon-pilot conversations run-turn <id> --text "Continue."    # existing conversation
   neon-pilot background-commands start --command "pnpm test"   # detached shell work
   neon-pilot tasks list                                        # scheduled behavior
   neon-pilot extensions list                                   # extension admin
   

   Use neon-pilot commands, neon-pilot commands --brief, and neon-pilot help <command> for command discovery. Use --json only when you are writing a script, need stable ids/schema fields, or must parse output mechanically.

2. From an internal Neon Pilot conversation, prefer the canonical tool for the same command surface:

   { "command": "list_admin_commands" }
   

   Use the shell CLI when the task is explicitly about external-user behavior, install/bootstrap from a terminal, or validating what a human will see.

3. Pick the conversation surface by intent. Use human output for orientation; add --json only when parsing:

   neon-pilot extensions list
   neon-pilot settings list
   neon-pilot conversations workspace      # open/sidebar state, usually what "active threads" means
   neon-pilot conversations open list      # ergonomic open/sidebar view
   neon-pilot conversations list           # persisted conversation history page, not open/active threads
   neon-pilot cli status
   neon-pilot control-plane doctor
   

4. Inspect before mutating shared state. For conversation/sidebar state, read the workspace first:

   neon-pilot conversations workspace
   neon-pilot conversations workspace update --open conv-a,conv-b --active conv-b
   

5. For extension work, use the lifecycle CLI and validate/reload after edits:

   neon-pilot extensions list
   neon-pilot extensions catalog
   neon-pilot extensions install system-example
   neon-pilot extensions validate system-example
   neon-pilot extensions reload system-example
   neon-pilot extensions delete system-example
   

6. Use normal shell commands for repository work such as pnpm, git, rg, and file validation.

Output modes

Default CLI output is for humans and agents reading transcripts. Prefer it when deciding what to do next.

Use --json for scripts, assertions, stable ids, machine parsing, and generated references. Do not use JSON simply because the caller is an agent; it costs more context and hides the product ontology behind schema noise.

Use commands --brief for compact agent-readable text. Use commands --verbose when you need advanced escape hatches such as schema export, app-command, or raw protocol surfaces. They are intentionally not emphasized in the default human command list.

Install and bootstrap

Use the packaged app and unified neon-pilot CLI control plane for external setup. Do not build from source unless the user asks for development setup. Neon Pilot control is not exposed through MCP.

Install the signed packaged app when starting from a clean machine:

curl -fsSL https://raw.githubusercontent.com/patleeman/neon-pilot/master/install.sh | bash -s -- --install-cli --bootstrap --json

Use --channel rc only when the user wants the release-candidate channel.

Never pass API keys in argv. Use stdin or OAuth/device flow:

neon-pilot bootstrap configure --secrets-provider keychain --provider openai-codex --model gpt-5.4 --cwd "$PWD"
printf '%s' "$OPENAI_API_KEY" | neon-pilot bootstrap provider set-key openai --stdin --json
neon-pilot bootstrap defaults set --provider openai-codex --model gpt-5.4 --cwd "$PWD"

For custom OpenAI-compatible providers:

neon-pilot bootstrap provider save openrouter --base-url https://openrouter.ai/api/v1 --api openai
neon-pilot bootstrap provider model openrouter openai/gpt-5.4 --context-window 272000

Before reporting setup complete, run script-friendly health gates:

neon-pilot cli status --json
neon-pilot bootstrap doctor --json
neon-pilot control-plane doctor --json
neon-pilot protocol neon-pilot-agent capabilities --json
neon-pilot protocol neon-pilot-agent run --prompt "Reply with ready." --tools none --json

If bootstrap doctor or control-plane doctor fails, fix the failed check before continuing. Common failures are: app not running, CLI not linked, no default provider/model, missing provider credential, stale extension discovery, or disabled Neon Pilot CLI settings.

Conversation administration

Use conversations ... commands for agent-side conversation management.

Important distinction:

• conversations workspace / conversations open ... = current workspace/sidebar state.
• conversations list = persisted conversation history, paginated; --scope all can return hundreds of historical conversations and does not mean active/open.
• conversations search = historical transcript/metadata search.

neon-pilot conversations workspace
neon-pilot conversations open list
neon-pilot conversations list --scope all
neon-pilot conversations search "query"
neon-pilot conversations inspect <id> outline
neon-pilot ask --model opencode-go/deepseek-v4-flash --cwd /repo "prompt"
neon-pilot conversations create --title "Thread" --cwd /repo
neon-pilot conversations ensure-live <id>
neon-pilot conversations send <id> --text "message"
neon-pilot conversations run-turn <id> --text "prompt" --timeout-ms 120000
neon-pilot conversations abort <id>
neon-pilot conversations compact <id>
neon-pilot conversations fork <id> --title "Fork"
neon-pilot conversations tools <id> bash read edit
neon-pilot conversations rollback <id> 1
neon-pilot conversations archive <id...>
neon-pilot conversations unarchive <id...>
neon-pilot conversations delete <id...>
neon-pilot conversations retention prune --older-than 90d --archived-only --dry-run

For sidebar/open-thread state, use workspace/open commands, not conversations list --scope all and not scope=running:

neon-pilot conversations workspace
neon-pilot conversations workspace update \
  --open conv-a,conv-b \
  --pinned conv-a \
  --active conv-b \
  --workspace-path /repo
neon-pilot conversations open list
neon-pilot conversations open add conv-a conv-b
neon-pilot conversations open pin conv-a
neon-pilot conversations open active conv-b
neon-pilot conversations archive conv-old
neon-pilot conversations unarchive conv-old
neon-pilot conversations delete conv-old
neon-pilot conversations retention prune --older-than 180d --archived-only --dry-run

Vocabulary:

• open/sidebar — conversations visible in the Threads sidebar / workspace state. Use conversations workspace or conversations open list.
• active — the currently selected sidebar conversation (activeConversationId), not every open conversation.
• history/persisted — all saved conversations. Use conversations list/search; --scope all means all historical persisted conversations.
• live/executing — conversations with a live runtime or active turn.
• archived — hidden from the normal sidebar/history views. Use conversations archive / conversations unarchive.
• delete — permanent conversation deletion. Use conversations delete; never delete session files directly.
• retention prune — bulk deletion by age. Start with --dry-run; use --archived-only unless explicitly asked to prune all old conversations.
• running — avoid this term unless a command explicitly defines it; it does not mean open/sidebar.

Extension, settings, and app command control

Use extension lifecycle commands before falling back to lower-level tools:

neon-pilot extensions list
neon-pilot extensions catalog
neon-pilot extensions create system-example --name "Example"
neon-pilot extensions install <catalog-id>
neon-pilot extensions update <catalog-id>
neon-pilot extensions install-url <bundle-url> --expected-id <id>
neon-pilot extensions enable <id>
neon-pilot extensions disable <id>
neon-pilot extensions snapshot <id>
neon-pilot extensions delete <id>
neon-pilot skills browse --source openai --json
neon-pilot skills search "code review" --json
neon-pilot skills preview <candidate-id> --json
neon-pilot skills install <candidate-id> --json
neon-pilot skills installed --json
neon-pilot skills search-state --json

Settings are schema-backed. Read schema before writes; use JSON values for set:

neon-pilot settings schema
neon-pilot settings get <key>
neon-pilot settings set <key> 'true'
neon-pilot settings set <key> '"string value"'
neon-pilot settings reset <key>

App/command-palette commands are available as an escape hatch. Prefer specific CLI commands when they exist; inspect before running command IDs with side effects:

neon-pilot commands --verbose
neon-pilot app-commands list --json
neon-pilot app-commands run <command-id> --args '{"some":"json"}' --json

Background work and automations

Use first-class CLI commands for durable work and scheduled automation:

neon-pilot background-commands list
neon-pilot background-commands start --command "pnpm test" --cwd /repo
neon-pilot background-commands logs <run-id> --tail 200
neon-pilot background-commands cancel <run-id>

neon-pilot tasks list
neon-pilot tasks save --title "Daily check" --cron "0 9 * * *" --prompt "Summarize status"
neon-pilot tasks run <task-id>
neon-pilot tasks delete <task-id>

neon-pilot heartbeats start <heartbeat-id> --interval-minutes 5 --conversation-id <conversation-id> --prompt "Wake up, check whether work remains, and stop this heartbeat when done."
neon-pilot heartbeats list
neon-pilot heartbeats stop <heartbeat-id>

Advanced internal delegated agent control

The same CLI surface also controls Neon Pilot as a delegated agent runtime. For a one-shot external delegation, prefer neon-pilot ask; it creates a normal conversation, runs one turn, and returns the answer plus conversation id. Do not direct external users to subagents; subagents are an internal model tool for Neon Pilot agents to create durable offshoot work.

Create a controlled conversation through the nested protocol surface only when you need stable conversation orchestration:

neon-pilot protocol neon-pilot-agent conversation create --title "External task" --cwd "$PWD" --tools default --json
neon-pilot protocol neon-pilot-agent conversation send <conversationId> --prompt "Continue." --json

Start and inspect durable agent work through the protocol control surface, not the public command list:

neon-pilot bootstrap doctor
neon-pilot bootstrap configure --provider openai-codex --model gpt-5.4
neon-pilot bootstrap defaults set --provider openai-codex --model gpt-5.4 --cwd "$PWD"
neon-pilot ask --model opencode-go/deepseek-v4-flash --cwd "$PWD" "Reply with ready."
neon-pilot commands --verbose
neon-pilot protocol neon-pilot-agent capabilities --json
neon-pilot protocol neon-pilot-agent run --prompt "Reply with ready." --tools none --json
neon-pilot protocol neon-pilot-agent start --prompt "Investigate this issue." --cwd "$PWD" --json
neon-pilot protocol neon-pilot-agent runs list --kind subagent --json
neon-pilot protocol neon-pilot-agent runs logs <runId> --tail 200

The protocol control surface is intentionally nested behind protocol/commands --verbose; do not present it as the normal user-facing way to ask Neon Pilot to work.

Sharp transcript operations

Transcript mutation commands are advanced recovery/admin tools. Inspect first and prefer safer conversation operations when possible.

neon-pilot conversations transcript append <id> --type text --data '{"text":"note"}'
neon-pilot conversations transcript update <id> <block-id> --type text --data '{"text":"replacement"}'

Boundaries

• Core owns the neon-pilot CLI shell and built-in commands such as commands, help, protocol, and cli status/install/uninstall.
• Extensions contribute product-specific CLI commands through contributes.cliCommands.
• control-plane doctor runs non-destructive smoke checks for command discovery, conversation APIs, retention dry-run, runtime repo root, and extension storage.
• app-commands run triggers extension/app commands by ID and is a broad escape hatch; prefer narrower lifecycle/settings/conversation/runs CLI commands for predictable JSON behavior.
• Built-in system extensions contribute the primary self-administration surfaces: extensions ..., settings ..., and conversations ....
• The agent shell receives Neon Pilot's channel-local CLI bin directory automatically. User shell installation is opt-in through neon-pilot cli install.
• Do not edit internal runtime files directly when an extension-contributed CLI command exists for the same operation.
• If the unified CLI surface lacks a needed Neon Pilot operation, add it to the shared command registry/service and expose it through both neon-pilot CLI and neon_pilot tool instead of adding a one-off tool, MCP endpoint, hidden-file workflow, or ad hoc script.