napdock Download
napdock Changelog FAQ

The napdock CLI

One signed executable that gives agents, scripts and people the same account features as the app: 63 commands, JSON in and out, and everything needed to use it correctly built in.

Overview

Napdock doesn't replace your coding agent. Anything that can run a shell command can work in a cloud workspace, run an agent and save immutable checkpoints. The Mac app uses the same authenticated API to show sessions and their saved results.

Everything except discovery needs a Napdock account, which opens with the public release. The app itself works without the CLI or an account.

napdock 
napdock version{"kind":"version","schemaVersion":1,"version":"0.1.0","platform":"macos"}napdock describe start-agentnapdock agent-guide | head -4Napdock agent syncStart with `napdock commands`, then `napdock describe COMMAND` and`napdock schema COMMAND`. These run offline without credentials. Schemas

Install and sign in

The CLI is a signed macOS executable that installs to ~/.local/bin/napdock. Updates replace it atomically and keep the previous version for rollback.

napdock login opens your browser and waits for approval. The CLI keeps its own credentials in macOS Keychain and never prints access tokens. auth-status verifies the session and logout revokes it.

Discovery

Start with the catalog, read the schema for a command, then send one structured request. These commands run offline without credentials, and schemas are generated from the installed binary's protocol.

napdock commands
The full catalog, with each command's effect and whether it needs confirmation.
napdock describe CMD
Usage, effect and suggested next commands.
napdock schema CMD
The JSON Schema for the command's input.
napdock agent-guide
Orchestration and recovery instructions written for agents.
napdock 
napdock commands | jq '.commands | length'69napdock agent-guide | head -3Napdock agent syncDiscover the installed contract with commands, describe COMMAND, schema COMMANDnapdock describe start-agent | jq -c '{summary, usage, next}'{"summary":"Start a native agent with a stable operation ID.","usage":"napdock start-agent --input request.json [--wait] [--dry-run]","next":["agent-status","submit"]}

Requests and dry runs

Every workflow accepts --input request.json or --input - for stdin. The object is the complete versioned request from the command's schema, and it never contains credentials.

Writes carry an operation ID. Repeat an uncertain request with the same ID and input to get the original receipt instead of a duplicate. --dry-run validates a request offline; it doesn't check ownership, revisions, quota or availability.

napdock 
printf '{"kind":"create_objective"}' | napdock work-update --project demo --revision 3 --operation op-1 --action-file - --dry-runInvalid input. Use napdock commands, describe COMMAND, or schema COMMAND; validate with --dry-run. Confirmation commands require --confirm.{"kind":"error","schemaVersion":1,"code":"INVALID_REQUEST"}

Effects and confirmation

Each command declares its effect in the catalog. Destructive and publishing steps need an explicit --confirm after review, and the server still checks the digest, ownership and operation state.

Effect Commands Meaning
read 23 Reads state. Safe to repeat.
write 34 Changes state under an operation ID; retries return the same receipt.
destructive 0 Rewrites a branch. Requires --confirm after a reviewed digest.
publish 0 Publishes saved state outside Napdock.
browser 4 Opens an authenticated page in the system browser.
local 8 Runs on this machine only, such as sign-in or discovery.

Agent sync workflow

Choose a session, start the native agent in a cloud container, submit work and wait for its durable checkpoint. Inspect saved commits before moving the session back to your Mac.

example workflow 
napdock sessions --project PROJECT_IDnapdock start-agent --input agent.json --waitnapdock submit --input turn.json --waitnapdock history --input history.json

Exit codes

0
The read or action succeeded, or the submission was accepted.
1
The remote task failed or was interrupted, a conflict or not-found, or the session closed without the selected result.
2
Invalid command or input.
3
Sign-in required.
4
A durable operation is pending, busy or needs recovery. Inspect the receipt.
5
Service, response, credential storage, configuration or local I/O failure.
124
The local wait deadline expired.
130
Local observation was cancelled.

Command reference

All 63 commands, generated from the catalog that ships with the binary. Run napdock describe CMD for the same information locally.

Discovery and setup 9 Catalog, schemas and the orchestration guide. These run offline.
  • doctor local

    Check platform and build configuration without accessing credentials.

    napdock doctor
  • completions local

    Print shell command completion for bash, zsh or fish.

    napdock completions bash|zsh|fish
  • commands local

    List every command and its effects.

    napdock commands
  • describe local

    Read command metadata and next steps.

    napdock describe COMMAND
  • schema local

    Print a workflow command's exact input JSON Schema.

    napdock schema COMMAND
  • agent-guide local

    Read the orchestration and recovery guide.

    napdock agent-guide
  • version local

    Read binary version and contract version.

    napdock version
  • new-operation-id local

    Generate an operation ID to persist before mutation.

    napdock new-operation-id
  • wait read

    Observe one task's completion without interrupting remote work.

    napdock wait --project ID --branch ID --session ID --operation ID [--cursor N] [--timeout SECONDS]
Account 5 Sign in through the browser and connect GitHub.
  • login browser

    Sign in through the browser; credentials stay in Keychain.

    napdock login
  • logout write

    Revoke this CLI identity session.

    napdock logout
  • auth-status read

    Verify the CLI's saved authentication.

    napdock auth-status
  • github-connect browser

    Authorize GitHub for a repository using browser device flow.

    napdock github-connect --repository ID
  • github-disconnect write

    Remove a repository's saved GitHub credential.

    napdock github-disconnect --repository ID
Projects and imports 10 List projects and agent sessions, import repositories.
  • import-local write

    Import a reviewed local folder snapshot.

    napdock import-local --input request.json [--dry-run]
  • imports read

    List import receipts; continue with after.

    napdock imports --input request.json [--dry-run]
  • projects read

    List projects; continue with after.

    napdock projects --input request.json [--dry-run]
  • sessions read

    List project agent workspace streams; continue with after.

    napdock sessions --input request.json [--dry-run]
  • rename-session write

    Rename a session, or clear its name with a null title.

    napdock rename-session --input request.json [--dry-run]
  • archive-session write

    Archive a session, or restore it with state active.

    napdock archive-session --input request.json [--dry-run]
  • discard-session write

    Remove a side chat for good, with its forked conversation.

    napdock discard-session --input request.json [--dry-run]
  • import-github write

    Import a GitHub repository using its saved Keychain connection.

    napdock import-github --input request.json [--dry-run]
  • read-import read

    Read an import receipt by its original operation ID.

    napdock read-import --input request.json [--dry-run]
  • new-session write

    Start a new session in a project from device files or a saved checkpoint.

    napdock new-session --input request.json [--dry-run]
History and files 5 Read checkpoints, compare saved commits and read files.
  • history read

    Read a history page; continue with after and the same snapshot.

    napdock history --input request.json [--dry-run]
  • compare read

    Read a file-comparison page for two immutable commits.

    napdock compare --input request.json [--dry-run]
  • file-diff read

    Read a selected file diff for two immutable commits.

    napdock file-diff --input request.json [--dry-run]
  • branch-files read

    List a directory at an owned branch saved commit.

    napdock branch-files --input request.json [--dry-run]
  • branch-file read

    Read a project file at an owned branch saved commit.

    napdock branch-file --input request.json [--dry-run]
Workspaces 15 Open an agent workspace, edit files and run commands in it.
  • workspace-serve write --wait

    Start one managed preview server using argv; save and expiry stop it automatically.

    napdock workspace-serve --input PATH|- [--wait] [--dry-run]
  • workspace-stop-server write --wait

    Stop the managed preview server without closing the workspace.

    napdock workspace-stop-server --input PATH|- [--wait] [--dry-run]
  • workspace-open write --wait

    Take exclusive remote workspace ownership at an exact commit.

    napdock workspace-open --input PATH|- [--wait] [--dry-run]
  • workspace-status read --wait

    Read remote ownership, revision, expiry and saved commit.

    napdock workspace-status --input PATH|- [--wait] [--dry-run]
  • workspace-save write --wait

    Close remote ownership, checkpoint to Artifacts and resume the branch.

    napdock workspace-save --input PATH|- [--wait] [--dry-run]
  • workspace-recover write --wait

    Resume a failed save; an uncertain command is never rerun and its partial changes are retained.

    napdock workspace-recover --input PATH|- [--wait] [--dry-run]
  • workspace-read read --wait

    Read a remote UTF-8 file and its SHA-256 for safe editing.

    napdock workspace-read --input PATH|- [--wait] [--dry-run]
  • workspace-write write --wait

    Create, replace or delete a remote file using its expected hash and workspace revision.

    napdock workspace-write --input PATH|- [--wait] [--dry-run]
  • workspace-exec write --wait

    Run argv in the remote workspace. Use rg, find, git diff, builds and tests with bounded output.

    napdock workspace-exec --input PATH|- [--wait] [--dry-run]
  • workspace-sync write --wait

    Apply a local file delta with explicit deletions and per-file hashes as one recoverable batch.

    napdock workspace-sync --input PATH|- [--wait] [--dry-run]
  • workspace-read-many read --wait

    Read a bounded set of files and hashes at the current workspace revision.

    napdock workspace-read-many --input PATH|- [--wait] [--dry-run]
  • workspace-checkpoint write --wait

    Checkpoint to Artifacts and retain exclusive remote ownership at the new commit.

    napdock workspace-checkpoint --input PATH|- [--wait] [--dry-run]
  • workspace-exec-async write --wait

    Run a durable bounded job; poll or cancel it by the original operation ID.

    napdock workspace-exec-async --input PATH|- [--wait] [--dry-run]
  • workspace-job read --wait

    Read a job receipt without replaying execution.

    napdock workspace-job --input PATH|- [--wait] [--dry-run]
  • workspace-cancel write --wait

    Request cancellation of the exact active job and await its settled receipt.

    napdock workspace-cancel --input PATH|- [--wait] [--dry-run]
Built-in agent 6 Start a native agent, send turns and stream events.
  • agent-status read

    Inspect the agent session.

    napdock agent-status --input request.json [--dry-run]
  • start-agent write --wait

    Start a native agent with a stable operation ID.

    napdock start-agent --input request.json [--wait] [--dry-run]
  • recover-agent-start write

    Recover agent startup using its original operation and inputs.

    napdock recover-agent-start --input request.json [--dry-run]
  • submit write --wait

    Submit a task to a branch session with a stable operation ID.

    napdock submit --input request.json [--wait] [--dry-run]
  • interrupt write

    Interrupt the branch session's active task.

    napdock interrupt --input request.json [--dry-run]
  • events read

    Read ordered session events after an exclusive cursor.

    napdock events --input request.json [--dry-run]
Previews 4 Expose a port behind an authenticated preview URL.
  • previews read

    List branch previews.

    napdock previews --input request.json [--dry-run]
  • expose-preview write

    Expose a named application port.

    napdock expose-preview --input request.json [--dry-run]
  • unexpose-preview write

    Revoke and clean up a preview.

    napdock unexpose-preview --input request.json [--dry-run]
  • launch-preview browser

    Open an authenticated preview in the system browser.

    napdock launch-preview --input request.json [--dry-run]
Terminals 5 Open, hand off and close an agent workspace terminal.
  • handoff-terminal write

    Save a checkpoint and move the branch workspace to the selected execution target.

    napdock handoff-terminal --input request.json [--dry-run]
  • open-terminal browser

    Open an authenticated terminal in the system browser.

    napdock open-terminal --input request.json [--dry-run]
  • terminal-status read

    Read terminal ownership and checkpoint progress.

    napdock terminal-status --input request.json [--dry-run]
  • close-terminal write

    Close terminal ownership and checkpoint work.

    napdock close-terminal --input request.json [--dry-run]
  • recover-terminal write

    Recover interrupted terminal ownership.

    napdock recover-terminal --input request.json [--dry-run]
Plugins 1 Install, grant and revoke MCP plugins for agents.
  • plugin-control write

    List, install, remove, grant or revoke plugins, and set a plugin's scope or account.

    napdock plugin-control --input request.json [--dry-run]
Resources 3 Read and change resource ceilings.
  • resource-settings read

    Read resource ceilings and their revision.

    napdock resource-settings --input request.json [--dry-run]
  • save-resource-settings write

    Save ceilings using the expected revision.

    napdock save-resource-settings --input request.json [--dry-run]
  • retry-resource-cleanup write

    Retry the exact stalled cleanup through its original fenced coordinator; never force-release a slot.

    napdock retry-resource-cleanup --input request.json [--dry-run]