CLOUDBROWSER DOCUMENTATION

CLI reference

A Go CLI for humans, agents and dependable shell scripts.

The CLI will be implemented in Go. This is the proposed command design; there is no install script or release binary yet.

Top-level commands

Use cloudbrowser create, not an additional browser subcommand. Commands below map to the same REST contract used by the console.

TERMINAL

cloudbrowser auth login
cloudbrowser create --name research --wait
cloudbrowser list --output json
cloudbrowser get br_123
cloudbrowser connect br_123 --ttl 1h --output json
cloudbrowser view br_123
cloudbrowser pause br_123 --wait
cloudbrowser resume br_123 --wait
cloudbrowser pause br_123 --wait
cloudbrowser fork br_123 --name copy --wait
cloudbrowser delete br_123 --yes
cloudbrowser usage

Connection management

TERMINAL

# Share URLs default to read-only and never expire
cloudbrowser view br_123 --output json
cloudbrowser view br_123 --permission control --expires-in 24h --output json
# Optional direct one-time entry; authorization deadline is separate
cloudbrowser view br_123 --one-time --ticket-ttl 5m --expires-in 24h

cloudbrowser links list br_123 --status active
cloudbrowser links update br_123 grant_123 --permission view --never-expires
cloudbrowser links sessions br_123 grant_123
cloudbrowser links end-sessions br_123 grant_123 --yes
cloudbrowser links revoke br_123 grant_123 --yes

# CDP retains its independent renewal manager
cloudbrowser connect br_123 --ttl 1h --auto-renew --max-lifetime 24h --watch
cloudbrowser tokens renew br_123 grant_cdp

view creates a Live View grant, opens its URL locally and exits. --output json or --no-open returns the URL without opening it. connect --audience live-view is an equivalent issuance command that does not open the URL. No agent label is required when creating a browser.

--permission view|control selects read-only or browser operation. --never-expires is the default; mutually exclusive --expires-in and --expires-at set an absolute authorization deadline (duration is converted to an RFC3339 timestamp at request time). --ticket-ttl controls the separate short-lived entry ticket. --one-time changes the URL to single-use entry instead of reusable sharing. Do not apply CDP flags --ttl, --max-lifetime or --watch to Live View. Live View automatically refreshes by default; --no-auto-renew limits each session to 5 minutes or the link deadline, whichever is sooner.

links list calls GET grants with audience=live-view; links update maps to PATCH grant, and links revoke maps to DELETE grant. Changing policy ends existing sessions; ending sessions alone preserves the reusable URL. Revoked links cannot be re-enabled. Link commands reject CDP grants; tokens renew accepts CDP only.

CDP --watch keeps an authenticated foreground manager running. Watch mode emits newline-delimited connected/renewed/expiring/expired events; ordinary commands emit one JSON object. Secrets appear only at issuance, never in listings.

Account library

TERMINAL

cloudbrowser library add --url "$LIVE_VIEW_URL"
cloudbrowser library list --source shared
cloudbrowser library view br_shared
cloudbrowser library remove br_shared --yes

Library commands use the signed-in account from auth login, not a workspace key. Adding access does not copy or transfer the browser. Removing a shared entry does not delete the owner’s browser. The account viewer URL expands the existing workspace rather than navigating to a separate detail UI.

Human and agent behavior

Option / convention	Design
--output table \| json	Human table output or stable machine-readable JSON.
--wait / --timeout	Wait for asynchronous operations with a bounded deadline. Timeout preserves the operation ID.
--idempotency-key	Stable create/fork identity across retries. CLI generates a key if omitted and reuses it for internal retries.
--yes	Explicit confirmation for destructive actions. Non-interactive runs otherwise fail rather than hang.
CLOUDBROWSER_API_KEY	Workspace key for agent and CI authentication. Never stored in connection URLs.
stdout / stderr	Results on stdout. Progress and diagnostics on stderr.
Exit codes	0 success; 1 service failure; 2 invalid arguments; 3 authentication; 4 quota; 5 timeout.

Distribution & credentials

Planned native builds for macOS, Linux and Windows; amd64 and arm64 where supported. Publish checksums with releases. Human login opens an account authorization flow; agent authentication uses a workspace API key. Local credentials should use the OS keychain or a restricted-permission config, never project files.

The CLI controls lifecycle and access. Browser interaction remains compatible with Playwright CLI, agent-browser and other CDP tools.

Private preview · REST API · CLI designExplore console