pithy dashboard status --env prodReports what is registered: the connection, its scopes, who authorized it, its kind and its purpose, and every key with its age and whether it is live.
Looking is free. Proving is opt-in
Connecting an environment is how one comes to exist, rotating and revoking a key is what to do when a check fails on the credential, and diagnosing a broken project is what to do when it fails on the Worker.
Reading the row costs nothing — it is your own database.
Proving the connection still answers costs a browser sign-in, because a signed ping needs the client’s private key and the client will not sign one for an unauthenticated request.
So the probe is behind a flag:
pithy dashboard status --env prod --verifyWithout it, the status is unverified — never connected. Status never claims a round-trip it did not make, and a report that guessed would be worse than one that says it did not look.
The three statuses
| Status | Means |
|---|---|
unverified | The row is there. Nothing was proven, because --verify was not passed |
connected | A signed ping round-tripped just now |
needs_reconnect | The row is there and the ping did not come back |
connected: false — the separate boolean — means nothing is registered at all. That is the shipped, denying state rather than a fault.
Reading a needs_reconnect
The row exists and the call did not land. Four causes, in rough order of likelihood:
The address moved. A custom domain, a renamed Worker, a changed route. The fix is a re-point:
pithy dashboard connect --env prod --update --worker-url https://api.example.comThe environment is not deployed. A connection registered against an environment that was never shipped, or one that has been taken down.
The base path changed. You moved where the seam mounts, and the stored path points at the old one. Also a re-point.
Every key is expired or revoked. status shows this directly: no key with live true.
The detail field carries the probe’s own sentence, which usually names which of those it was.
What the key list tells you
Every registered key, live and superseded, with:
- Its id, as a token names it
- Whether it may verify a call right now
- Its age in whole days — the number a rotation policy is read against
- When it became valid, when it expires if it does, and when it was revoked if it was
Two live keys is a normal state during a rotation, not a fault.
Who authorized it, and what for
Authorized by is the email of the signed-in session that registered the connection. Kind is dashboard, agent or script. Purpose is what the client is for, in the registering operator’s words — the line a review of this credential reads. Under --json they are authorizedBy, actorKind and purpose.
A connection registered before these were recorded keeps working, and status says it was registered before principals were recorded. pithy dashboard connect --update --purpose sets its purpose; registering again records who authorized it.
Checking from CI
pithy dashboard status --env prod --json--json implies non-interactive, so --verify cannot run a browser flow there — a scheduled check reads the row, the scopes and the key ages, which is what a rotation policy needs anyway.
What it does not tell you
Whether the dashboard is up. This reads your row and, with --verify, calls your Worker. Their availability is their status page.
What the connection has been doing. That is your audit trail, where every control-plane call lands under its own actor type, stamped with the connection’s kind — reads included.
Whether a scope is being used. Granted and exercised are different facts, and only the trail knows the second.
The audit capability counts it for you. Its usage read, behind audit:events:read, gives one row per scope and key a connection used over a window, with its allowed and refused calls counted and the last of each, so a grant that never shows up there is a grant nobody exercises. Refusals are included, so a connection asking for what it lacks shows up too.