Cloud commands

Upload runs and baselines to a Dungbeetle cloud server, and manage this machine's stored credential. See the Cloud server guide.

login

Connects this machine to a cloud server as an agent via the device flow: prints a one-time code and a /ui/connect URL, waits while you approve in a browser (any browser, any machine — the code links them), then stores the minted dbat_… token at $XDG_CONFIG_HOME/dungbeetle/credentials.json (mode 0600, keyed by server origin).

dungbeetle login --label "CI runner" --scopes runs:write baselines:write

Flag	Meaning
--server <url>	Server base URL (or DUNGBEETLE_SERVER_URL). Defaults to the hosted cloud (https://dungbeetle.dev); set only when self-hosting.
--label <name>	Agent label shown in the dashboard (default dungbeetle CLI on <hostname>).
--scopes <scopes...>	Requested scopes; default is the Triage preset.

logout

Revokes this machine's agent token on the server (best-effort — the local credential is removed even if the server is unreachable) and forgets it. Takes --server <url> when self-hosting; defaults to the hosted cloud.

Credential resolution

Every cloud command resolves the server URL first: --server, then DUNGBEETLE_SERVER_URL, then the hosted cloud (https://dungbeetle.dev) — set either only when self-hosting. push and push-baselines then pick credentials in this order:

1. Explicit client credentials — --client-id / --client-secret flags or the DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET environment variables (sent as HTTP Basic, unchanged for CI).
2. Stored agent token — whatever dungbeetle login saved for that server origin (sent as Bearer).

Neither present → an error telling you to run dungbeetle login or pass the pair.

push

Uploads a JSON run report (selected with --report <path>) to a cloud server. --branch <name> and --commit <sha> label the run in the history and review timeline. --description <markdown> attaches a markdown description, rendered as the Description section of the run review page.

push-baselines

Uploads local baselines to a cloud server, versioned per (project, target). A new version is created only when the content digest changes. --target <name...> scopes the upload.

anon

Captures a target and shares it on a cloud server without an account — the link is public, read-only, and deleted after 24 hours.

# Share a one-off snapshot of a page
dungbeetle anon https://example.com

# Compare two pages and share the semantic diff + screenshots (the good demo)
dungbeetle anon https://dungbeetle.dev/demo \
  --compare "https://dungbeetle.dev/demo?v=2" --screenshot

# Or capture a command's output instead of a URL
dungbeetle anon --cmd "my-cli --version"

With --compare the first URL is captured as the baseline and the second as the candidate; the shared page leads with the node-level semantic diff — exactly what test reports in CI. --screenshot adds full-page screenshots (via a local Chrome/Chromium; the trial degrades gracefully without one), so the shared page also gets the side-by-side / onion-skin visual comparison. --name labels the capture; the share target defaults to the hosted cloud — --server <url> (or DUNGBEETLE_SERVER_URL) overrides it when self-hosting.