CLI setup reference

New to Viewport? Start with the Quickstart — it reaches a governed run and its receipt in about ten minutes. For the event-triggered GitOps path, see Self-serve first run. This page is the command reference behind both: what vpd installs, and how the worker and monitor pairing profiles differ.

Install

npm install -g @viewportai/daemon
vpd --version

vpd install prepares local runtime files only. It does not silently install Claude/Codex hooks, skills, MCP servers, or shell integrations.

Team Worker Path

Use this when a workflow should execute on your machine, dev box, or VPS:

vpd pair PAIRING_CODE --worker --transport=polling --workdir "$HOME/.viewport/worktrees"
vpd worker doctor --json
vpd worker start --mode persistent --transport polling

Hosted Viewport is the default server. For a self-hosted or customer-internal control plane, pass the server at pair time:

vpd pair PAIRING_CODE --worker --server https://viewport.customer.internal --transport=polling --workdir "$HOME/.viewport/worktrees"

The worker profile is scoped to workflow execution. It can claim authorized leases and sync receipts. It does not by itself grant repo writes, Slack posts, GitHub PRs, or context updates.

Personal Monitor Path

Use this only when you want Viewport to observe local interactive agent sessions:

vpd pair
vpd bind ~/code/my-repo

Pairing and binding are separate. Pairing proves the machine to a workspace. Binding opts a directory into monitoring. A paired machine with no bound directory does not stream local sessions for that workspace.

Doctor Commands

vpd doctor
vpd status --json
vpd worker doctor --json

Use vpd worker doctor --json before debugging a workflow run. It should show the paired server, workspace, runner identity, workspace root, transport, detected agents/tools, and whether the runner is claimable.

Where Config Lives

Default local state lives under ~/.viewport/. Use VIEWPORT_HOME or VPD_HOME for isolated installs, CI tests, or throwaway proof machines.

Do not commit local pairing files, worker identity files, lease tokens, or doctor output that includes secrets.