CLI

vpd ships with @viewportai/daemon (current local source: 0.2.1). The binary is wired at viewport/packages/daemon/bin/vpd.js; the source of truth for help text is cli/lifecycle-commands.ts:312-457.

npm i -g @viewportai/daemon
vpd --help

Group-by-surface below. Every command listed here is implemented in code as of the audit.

Lifecycle

vpd start

Launches the daemon. Two-process supervisor + worker model.

State files: ~/.viewport/runtime.json, plus pidfiles. Resolves VIEWPORT_HOME / VPD_HOME first.

vpd stop

Sends a graceful shutdown via the lifecycle channel. Optional --force to send SIGKILL to the process group. --timeout SECONDS controls how long to wait, --json for machine-readable output.

vpd restart

Stops, then re-launches with the previously persisted launch config.

vpd status

GET /health from the running daemon plus pidfile checks. Reports running / stopped / unresponsive. Pass --check-updates to also query npm for the latest CLI version. Output sections: Status, Runtime, Home, Listen, Owner PID, Worker PID, Profile, Server, Relay WS, Relay state, Node, npm, CLI, Latest CLI, Update, Sessions, Directories, Agents.

vpd doctor

Read-only environment check. Prints daemon identity (machineId, version, runtime kind, home, scope, profile), control-plane endpoints, relay state, config source path, and recovery hints.

vpd doctor does not repair anything. If something is wrong it tells you where to look.

vpd setup

First-run guided setup.

vpd install

Detects available agents (Claude, Codex, Aider, Gemini via BUILT_IN_AGENTS) and installs hooks. Today only the Claude Code hook installer is wired; Claude Code is the primary integration.

Output:

[+] claude-code found at /usr/local/bin/claude
[-] codex not found
[-] aider not found
[-] gemini not found

Installing Claude Code hook... installed

vpd update [--yes]

Updates the daemon npm package. With --yes, also restarts the running daemon to pick up the new binary.

vpd service install|uninstall|status

Manages a launchd (macOS) or systemd (Linux) unit so the daemon auto-starts on login / boot.

Pairing

vpd pair [CODE] [--server URL] [--app-url URL]

The entry point.

• No CODE: mints a fresh 8-char code via POST /api/pairing-codes, prints it, opens your browser to {appUrl}/pair?code=…, polls /api/pairing-codes/{code}/status until approval.
• With CODE: claims a web-initiated code by calling POST /api/pairing-codes/{code}/claim.

On approval the daemon receives relay_credentials, persists them to ~/.viewport/config.json, and auto-restarts.

--server and --app-url override the default Viewport URLs (useful for self-hosted relays pointed at your control plane).

vpd pair anchor

Prints the daemon's trust anchor fingerprint. Used when verifying a daemon's identity out-of-band.

vpd pair rotate-token

Rotates the on-disk daemon auth token via rotateAuthToken(). Restart the daemon to pick up the new token.

Note: vpd unpair is not implemented as a CLI command today. To detach a daemon, DELETE /api/workspaces/{workspace}/installs/{install} from the web UI under Settings → Machines.

Directories

vpd add PATH

Registers a directory in the global config and POSTs to /api/directories on the running daemon so it picks up the change live.

vpd remove PATH

Unregisters via DELETE /api/directories/:id.

vpd list

Lists registered directories and active sessions.

Sessions

vpd run [DIR] --prompt TEXT

Connects to the daemon over WebSocket, auto-registers the directory if needed, sends a launch request, and (optionally) streams session-update events back.

vpd send SID --prompt TEXT

Sends a prompt message to an existing session.

vpd logs SID [--follow]

Subscribes via WS, replays messages from --last-seq N if provided, renders text updates (agent-message, tool-call, etc.) or --json.

vpd wait SID [--timeout]

Subscribes and blocks until session-ended arrives.

vpd attach SID

Equivalent to vpd logs --follow.

vpd ls

Lists sessions. Flags: --scope ALL|ACTIVE|DISCOVERED, --directory ID, --agent ID, --json or --format FMT.

vpd session stop SID

Sends a kill request for the session.

vpd session manifest --session SID

Prints the provider, workflow, and approval manifest for the session: what context was attached, which workflows applied.

vpd permit ls|allow|deny

Manages pending permission requests (Claude Code tool-use gates surfaced over the daemon hook bridge).

vpd agent mode SID [detect|bypass]

Reads or sets operator control mode for an active session.

Worktree

vpd worktree ls|diffs|summary|rollback|retry|squash

Operator-side worktree primitives backing the safe-edit model:

• ls: list worktrees
• diffs: show pending diffs vs HEAD
• summary: short status overview
• rollback: revert to a specific SHA (--to SHA)
• retry: branch-retry from a SHA (--from SHA)
• squash: squash-merge worktree into a target branch with a commit message

These map to the WS commands rollback, branch-retry, squash-merge (see API).

Workflows

vpd workflow validate PATH

Validates a workflow YAML file against schemas/workflow-v1.schema.json (Ajv-backed).

vpd workflow run PATH

Runs a workflow. --input k=v for inputs.

vpd workflow runs [--limit N]

Lists recent runs.

vpd workflow show RUN_ID

Shows run detail (status, current node, recent events).

vpd workflow rerun RUN_ID

Re-runs an existing workflow with the same inputs and YAML snapshot.

vpd workflow approve RUN_ID NODE_KEY [--message]

Approves a paused managed-approval gate.

vpd workflow cancel RUN_ID

Cancels an in-flight run.

Config

vpd config resolve

Resolves repo-local .viewport/config.yaml (or .viewport/config.json) and prints the resolved resources.

vpd validate [--path FILE]

Validates a repo-local Viewport config against viewport-config-v1.schema.json.

vpd contract resolve [--path FILE]

Resolves the contract manifest for a path.

vpd guard check --path FILE

Runs the policy guard against a specific file. Useful in pre-commit hooks.

Context Vault

The vpd context family manages encrypted shared memory (see Context Vault).

vpd context init
vpd context user-init             # passphrase or macOS keychain identity
vpd context join
vpd context status
vpd context add
vpd context propose
vpd context resolve
vpd context sync-push
vpd context sync-pull
vpd context identity-export
vpd context identity-import
vpd context device-request
vpd context device-approve
vpd context device-accept
vpd context grant

Many sub-commands accept --passphrase, --recovery-code, and --key-store file|macos-keychain.

Agent skills

vpd skills install [claude-code|cursor|all]

Writes per-agent contract markdown into a target path so the agent prompt-references vpd. Pass --force to overwrite. This is the magic that makes "Claude knows about vpd" work end-to-end.

Remote

vpd remote login|status|enable|disable|logout

Manages daemon-native relay transport options. Useful for switching between hosted relay, self-hosted relay, and disabled remote.

Hooks

vpd hook notify|plan|capabilities

Used by Claude Code hooks that vpd install writes into ~/.claude/settings.json. Not typically called by humans.

Internal

vpd __supervisor and vpd __worker are the daemon's two-process model. Don't invoke them directly.

What's persisted on disk

~/.viewport/
├── config.json              # daemon config (mode 0600)
├── runtime.json             # daemon runtime state (pid, listen address)
├── relay-identity.json      # daemon device identity for relay handshakes
├── plugins.json             # workflow plugins loaded at startup
├── replay/                  # session replay event store
├── sessions/                # per-session message logs (driven by directory + session id)
├── pairing-*                # in-progress pairing identity / file stores
└── ...

Override the root path with VIEWPORT_HOME or VPD_HOME. Repo-scoped daemon overrides (separate from the repo's .viewport/config.yaml contract) can be opted into with VIEWPORT_RESOURCE_OVERRIDE_DIR.

Related

• Quickstart for the minimal flow end-to-end
• Sessions for what vpd run produces
• Workflows for what vpd workflow operates on
• API for the WebSocket protocol the CLI speaks to the daemon