pithy dashboard

Register a management client’s access to one of your environments — by a key it holds, or by a trust in a workload’s own identity — rotate its key, revoke it, and inspect what is registered.

Synopsis

pithy dashboard connect [--env <environment>] [--worker <name>] [--worker-url <url>] [--scope <scope>]… [--purpose <text>] [--update] [--public-key <file> --issuer <url> --kind <agent|script> [--key-id <id>]] [--project <name>] [--origin <url>] [--no-open] [--json]
pithy dashboard connect --oidc-issuer <url> --oidc-claim <name=value>… --kind <agent|script> [--oidc-audience <aud>] [--env <environment>] [--worker <name>] [--worker-url <url>] [--scope <scope>]… [--purpose <text>] [--json]
pithy dashboard rotate [--env <environment>] [--worker <name>] [--origin <url>] [--no-open] [--json]
pithy dashboard revoke-key --key-id <id> [--env <environment>] [--worker <name>] [--yes] [--origin <url>] [--json]
pithy dashboard revoke-trust --trust-id <id> [--env <environment>] [--worker <name>] [--yes] [--origin <url>] [--json]
pithy dashboard disconnect [--env <environment>] [--worker <name>] [--yes] [--local] [--origin <url>] [--no-open] [--json]
pithy dashboard status [--env <environment>] [--worker <name>] [--verify] [--origin <url>] [--no-open] [--json]
pithy dashboard connections --principal <email> [--env <environment>] [--worker <name>] [--revoke --reason <text> [--yes]] [--json]

You run these, against your own project. They are the CLI half of the control-plane seam: the commands by which you grant a management client — the hosted dashboard, or one you wrote yourself — the right to call your Worker’s administrative routes, and by which you take that right back.

Every registration is a row in your D1. Your Worker is the authority; the management client is a client.

Connection is project-wide, per environment — never per Worker. Workers share a resource by binding name unless one owns it (naming), so one user record lives in one D1 that several Workers touch. A per-Worker credential would produce a management view where a user is visible in one pane and absent from another. --worker is only how the CLI finds the app database; the row is keyed on --env. The connection reaches one app database per environment, so with a Worker owning DB it covers one of the two databases, not both.

Registering takes a signed-in session, in every environment. A connect that creates a connection, or puts a new key on one whose every key you revoked, records who authorized it, and reads that from your pithy cloudflare connect session — the email GET /user names under it. An account token, a session with no email, or no credential at all is refused before anything is written, --env dev included. No flag supplies the principal. CI’s account token keeps migrating and deploying; it registers nothing.

What needs what. --env dev resolves the database from a local Miniflare store and needs no Cloudflare account; a deployed environment reads and writes real D1 over the REST API, which needs the credential pair. Separately, connect, rotate, disconnect and status --verify call the management client and run a browser device-code flow, which needs a human at a browser. Three paths avoid that: connect --public-key and connect --oidc-issuer, which contact no dashboard at all, and disconnect --local, which skips the courtesy call. revoke-key and revoke-trust never contact anyone. --oidc-issuer does read the issuer’s own discovery document, once, to check it.

Flags

FlagApplies toDefaultPurpose
--env <environment>all but connectionsdevThe environment whose registration is being read or written
--worker <name>all sevenresolvedWhich Worker resolves the app database. On connect it also names the Worker that composes the admin surface
--origin <url>all but connectionsthe connection’s own, else https://app.pithy.shThe management client’s origin. Re-points every call at a self-hosted one, and records the move
--no-openall but connections, acting on the four that sign inoffersNever offer to open the approval page. PITHY_NO_OPEN, at any value, does the same
--worker-url <url>connectresolvedOverride the resolved Worker URL for this environment. The only way to say so when a proxy fronts your Worker
--scope <scope>connectthe seam’s own, plus every declared readGrant one scope, narrowing the default. Repeatable — the raw argv is read, so several survive. --scope all grants every scope the Worker composes
--purpose <text>connectasked at a terminalWhat this client is for, in one line of plain text, 200 characters at most. Required to register a connection, and refused when absent without a terminal. With --update, replaces the stored one
--updateconnectfalseRe-point an existing connection’s URL, scopes or purpose instead of creating one
--public-key <file>connect—Register a JWK you generated yourself. No dashboard is contacted
--issuer <url>connect—With --public-key: the iss your own client presents. Required on that path, and rejected off it
--kind <agent|script>connect—With --public-key or --oidc-issuer: what kind of client it is. Required to register a connection on those paths, and rejected off them — the device-code flow is the dashboard, always
--oidc-issuer <url>connect—Register a workload trust: the exact iss its OIDC tokens carry, an https URL. No key and no dashboard. Not with --public-key or --update
--oidc-claim <name=value>connectasked at a terminal for a known issuerWith --oidc-issuer: a claim the workload’s token must carry. Repeatable, and at least one is required — an issuer alone accepts every workload it serves. Rejected off that path
--oidc-audience <aud>connectthis environment’s Worker originWith --oidc-issuer: the aud its tokens must name. Rejected off that path
--key-id <id>connectthe JWK’s kidWith --public-key: the key id, if the JWK carries none
--key-id <id>revoke-keyrequiredThe key to revoke, as status reports it
--trust-id <id>revoke-trustrequiredThe trust to revoke, as status reports it
--project <name>connectthe root config’s nameOverride the project name sent to the management client
--yesrevoke-key, revoke-trust, disconnect, connectionsfalseSkip the confirmation. How CI runs the same command, and required wherever nothing can be asked: without it, --json, --no-input, PITHY_NONINTERACTIVE=1 or a run with no terminal fails input/required rather than going ahead. On connections it answers --revoke’s question
--localdisconnectfalseDelete the row without telling the management client
--verifystatusfalseProve the connection with a signed ping
--principal <email>connectionsrequiredThe email whose connections to list, matched without regard to case
--env <environment>connectionsevery environment pithy.config.ts declaresRead one environment instead of all of them
--revokeconnectionsfalseRevoke every key and trust not yet revoked on each connection the principal authorized, after showing them. Destructive: a line that needs it is a person’s decision, never a fix
--reason <text>connections—Why they are revoked. Required with --revoke, and recorded on every revocation
--jsonall sevenfalseOne line of machine-readable output. Implies non-interactive: the o key is not offered. --no-input and PITHY_NONINTERACTIVE=1 do the same without --json

Every subcommand writes its machine output to stdout and its diagnostics — the device code, the waiting line — to stderr, so a --json consumer parses one clean line.

What it does

connect

Registers a management client against one environment — connecting an environment walks the same act from the dashboard’s side. It resolves the address from your project rather than demanding it: the Worker’s domains declaration for that environment, else its first routes pattern, else a hand-set vars.BASE_URL. It prints what it found and where it came from before registering.

It also sends the seam’s base path — the mount point — because that is the one address a client cannot discover, and a wrong one registers cleanly, passes the ping, and then 404s every call.

Then the device-code flow: a short user code, your browser, your approval. At a terminal it offers to open the approval page for you — press o — and --no-open, or PITHY_NO_OPEN at any value, turns that offer off. The management client generates the Ed25519 keypair, keeps the private half, and returns the public one; the CLI writes it into your D1.

Nothing reports connected until a signed ping round-trips against your Worker. A registration that was written but cannot be reached is a dead link, and reporting it as connected is how an operator finds out weeks later — so that case is needs_reconnect, and the command deliberately does not print Done.

The client’s response is checked, not trusted. A scope it returns that you did not request is a management client trying to widen its own grant, and the connection is refused outright rather than quietly stored narrower.

--public-key is the offline path: register a key you generated, with no dashboard involved. Nothing proves that key — the CLI holds no private half to sign with — so the status is registered, and the command says so.

A workload trust instead of a key

--oidc-issuer registers an OIDC trust: a trusted issuer, the audience its tokens must name, and the claims that say which workload a token was minted for. It is for an agent that runs unattended — in CI, a container, a job — where a private key would have to be placed and kept with nobody at a terminal. With a trust there is nothing to place: the workload asks its own identity provider for a short-lived token and presents it on every call.

pithy dashboard connect --env prod --oidc-issuer https://token.actions.githubusercontent.com --oidc-claim repository_id=1262274726 --oidc-claim environment=prod --kind agent --purpose "Nightly audit summarizer."

At least one claim, and it is the boundary. An identity provider signs for everybody with the same keys, so a trust with no claim constraint would accept every workload that provider serves. It is refused at registration, naming why.

For a known issuer, one claim must name the workload. GitHub signs for every repository and GitLab for every project, so a trust matching only on what the job is — environment=prod, ref=refs/heads/main, ref_type, event_name — admits anybody who creates a repository with that environment or branch. It is refused, naming the claim to add. The claims that count: for GitHub repository_id, repository, repository_owner_id, repository_owner, sub, workflow_ref and job_workflow_ref; for GitLab project_id, project_path, namespace_id, namespace_path and sub. A custom issuer is held to shape only, because nothing here knows which of its claims name a workload.

Match named claims rather than the sub string, and prefer an immutable id: repository_id over repository, project_id over project_path. A numeric id survives a rename and cannot be claimed by a same-named project elsewhere. A name is accepted, and the command says the trade once.

Known issuers are asked at a terminal. For GitHub Actions and GitLab CI, --oidc-issuer with no --oidc-claim at a terminal asks for the recommended claims one at a time, each with an example. The first, the immutable id, must be answered; the rest may be skipped. Any other issuer is custom: name the claims yourself. A claim no profile knows is never refused, so a claim from a customized subject template registers beside one that names the workload.

The audience defaults to this environment’s Worker origin, the address connect resolves and prints, which is what stops a staging token being replayed against production. --oidc-audience overrides it.

What is checked, and what is reported. The issuer’s discovery document must resolve, name that issuer, and point at a key set that parses; anything less refuses the registration and writes nothing. That is all a registration can prove — there is no private key here and no workload present — so the status is awaiting_first_call, never connected, and status keeps saying so until a call verifies under the trust.

How a workload calls. Every call presents its token on pithy-control-plane-oidc, names the trust on pithy-control-plane-trust, and names the one scope it exercises on pithy-control-plane-scope. Your Worker verifies the token per call against the trust’s issuer, audience and claims, and checks the scope against the connection’s grant exactly as it does for a key. Nothing is exchanged for the token. A captured token replays against this one audience until it expires — the provider’s lifetime, minutes.

A refused call records what it carried. When a token’s signature, issuer and audience verify and its claims do not match, the controlplane/call_denied row in your audit trail names the claims the token carried, as observedClaims. Register the trust, let the workload run once, and read the claims it actually sent. Before those three verify, nothing is recorded.

One connection, two credential kinds. A trust joins the environment’s connection if there is one, beside its keys, and leaves the connection’s grant, kind and purpose alone; the trust records who sanctioned it. Those three belong to the connection and every credential on it shares them, so --scope, --kind and --purpose on a join are refused rather than dropped, and no scope prompt is shown. To change the grant, run connect --update --scope, which changes it for the whole connection. With no connection, it registers one holding only the trust, with --kind and --purpose required as for --public-key. A signed-in session is required either way. A workload calling under a trust cannot register or expire a key, whatever the grant.

Who authorized it, what kind of client, and what for

Every connection a connect creates records three things on your row, beside the grant.

  • Authorized by — the email of your signed-in session. Derived, never typed.
  • Kind — dashboard on the device-code path, always. --public-key and --oidc-issuer take --kind agent or --kind script, said out loud. Your Worker stamps it onto every control-plane audit row the connection’s calls write, so a row says which of the three acted.
  • Purpose — what the client is for, in your words. --purpose, or asked at a terminal. One line of plain text: a control character, a line break or a bidi override is refused, because each is how a sentence turns into something else once a terminal or a review screen shows it.

The session and the purpose are settled before anything else happens — before the browser approval, before the management client records anything — so a refusal changes nothing anywhere.

--update --purpose edits the purpose and records controlplane/connection_updated with the old value and the new. The principal and the kind are facts of the registration; registering again is the only way to change them.

A connection registered before these were recorded keeps working. status shows it as registered before principals were recorded, --update --purpose sets its purpose, and registering again records who authorized it.

What a connect grants

The default is every read your Worker declares, plus the seam’s own two. Connecting produces a management client that can actually read, without a second command — which used to be the whole problem: a connection holding only the seam’s scopes opens a dashboard where every pane says the credential does not cover this call, and looks like a broken product rather than a grant nobody made.

It is derived, never listed. Each capability declares its admin routes with the scope each one needs, and connect reads that off the Worker it is registering. So a capability you add is offered on your next connect with no coordination, and a capability you do not compose is never mentioned.

A read is a route, not a name. A scope joins the default only when every declared route requiring it is a GET, or a POST that declares both kind: "reads" and readInBody: true — a read whose input travels in its body because a URL is written to every request log: a lookup by an address (POST /email/suppressions/lookup, POST /control-plane/connections/lookup), a search by a term (POST /auth/admin/users/search, POST /support/threads/search), an export with its reason (POST /auth/admin/users/:userId/export). The type a capability declares its routes with compiles readInBody only beside kind: "reads" on a POST. Any other method, or a POST without both declarations, is a write. Scope matching is exact — no prefixes, no wildcards — so holding a scope confers every route that requires it, and one mutating route anywhere makes the whole scope a write however it is spelled.

Connect with this CLI or newer. An older one counts only a GET as a read, so it reads those POSTs as writes and leaves the scopes they share out of the default: email:suppressions:read, connections:read, auth:users:read, auth:users:export and support:threads:read. It under-grants and never over-grants. Add them with --update, or connect again.

At a terminal, connect lists every operation your Worker exposes, described in each capability’s own words, preselected to that default — because narrowing is the point of showing the list. a toggles all of them and i inverts the selection, and the prompt says so. --scope answers the same question non-interactively and narrows to exactly what you pass; --scope all grants every scope the Worker composes. An explicitly empty selection is passed through as empty rather than collapsed into the default: an operator who deselected everything must not be handed a scope anyway. On an update, no --scope means “leave the grant alone”.

Whatever you end up with is printed and stored on your row, and your Worker enforces that row and nothing else. A narrowed grant refuses every call it left out with controlplane/insufficient_scope, and the manifest tells a client which routes those are before it tries.

A connection made before a scope existed does not hold it. migrations:read, privacy:read, evidence:read, processing:read, erasure:read and retention:read are the ones to know. A connection made before the seam reported migration state gets no migration route and no migration counts on the manifest until it is granted migrations:read. One made before the privacy inventory gets no GET /control-plane/privacy until it holds privacy:read, one made before the evidence pack gets no GET /control-plane/evidence until it holds evidence:read, one made before the record of processing gets no GET /control-plane/processing until it holds processing:read, one made before the erasure attestation gets no GET /control-plane/erasure until it holds erasure:read, and one made before legal holds gets no GET /control-plane/holds, and no count of standing holds on the manifest, until it holds retention:read. retention:hold, which places and releases a hold, is a write: offered, never granted by default. The manifest’s privacy block needs only manifest:read, because it names classes and counts and never a field. The upgrade is --update --scope with the new scope, and every scope the connection already holds passed beside it. --scope names the whole grant, so passed alone it narrows the connection to that one scope. --update --scope all adds it too. pithy dashboard status prints what the connection holds now.

$ pithy dashboard connect --env prod --update --scope manifest:read --scope keys:rotate --scope migrations:read --scope privacy:read --scope evidence:read --scope processing:read --scope erasure:read --scope retention:read

rotate

Appends a successor key and proves it. It never expires the old one, and that ordering is the entire safety property: append, prove, then expire — with expiry belonging to the management client once it has proven the successor from its infrastructure.

Two live keys is a normal state. A stale key costs nothing; expiring one that turns out to be the only working credential costs the connection, with no authenticated path back.

revoke-key

Stamps one key revoked, immediately. It is the narrow instrument beside disconnect’s blunt one: a client that leaked a single key does not need the whole connection rebuilt.

Purely local — it writes to your own D1 and tells nobody, which is what immediate and unilateral has to mean. It will take the last live key if you ask it to, because an adopter holding a leaked key must never be told they have to keep trusting it; the connection is then denying every call, and the command says so plainly.

revoke-trust

Stops honoring one trust, immediately: every call naming it is refused from the next one on. Purely local, like revoke-key. A token cannot be revoked, only the trust, so a token already minted stays in its holder’s hands until it expires, and the command says so when it revokes. disconnect says the same when the connection it removes held a live trust.

disconnect

Deletes the registration. The row goes first, and the management client is told afterwards as a courtesy that cannot fail the command — a dashboard that is down must not be able to keep a credential alive. Re-running it is not an error.

status

Reports what is registered: the connection, its scopes, who authorized it, its kind and its purpose, every key with its age and whether it is live, and every trust with its issuer, the claims it admits and whether it is awaiting a first call. Looking is free; proving costs a browser sign-in, so the probe is opt-in behind --verify and its absence is reported as unverified rather than guessed at.

connections

Lists everything one person authorized, across every environment the project declares: each connection’s kind, purpose, credential kind, scopes, every trust’s subject constraint, when it was registered, and whether anything on it is still live. It is the command for when somebody leaves. It reads the same function a management client’s POST /control-plane/connections/lookup does, so the two never list different things. The match is on the email the connection recorded, without regard to case.

A connection registered before principals were recorded is listed apart, for you to read, and is never revoked by a principal match.

--revoke shows what it will end, asks, then revokes every key and trust on each one not yet revoked, including one whose window has not opened, and records controlplane/connection_revoked with your --reason on that environment’s trail. Like revoke-key, it is local and tells nobody. A token already minted under a revoked trust stays usable until it expires, and the command says so.

A revocation stays revoked. No later CLI write revives it: a key rotation and a revocation each write only while the row still holds what they read, and connect --update never touches the credentials.

$ pithy dashboard connections --principal ada@example.com --revoke --reason "Left the company."

Opening the approval page

connect, rotate, disconnect and status --verify sign in through the device-code flow, and each one states a key while it waits:

Open https://app.pithy.sh/connect?userCode=ABCD-EFGH to approve.
Check that the page shows ABCD-EFGH.
Press o to open the link in the browser.
▸ Waiting for approval...

The Press o line is a stated key, not a prompt. The command is already polling and finishes whether or not you touch the keyboard, so there is nothing to answer and nothing that can hang. Press o and the approval page opens in whatever browser your machine already prefers — through open on macOS and xdg-open elsewhere. Ignore it and the first line still has the link, which is what you need when the browser is on another machine.

The link carries the code, and the code gets a line of its own. The link is your management client’s verificationUriComplete: the approval page with the code already filled in. You still choose an account and approve on the page. The second line prints the code by itself so you can check that the page shows the same one. A client that sends no verificationUriComplete gets the plain page and the code to type instead, and that plain page is what o opens:

Open https://app.pithy.sh/connect and enter ABCD-EFGH.

Either address has to sit on the origin you are signing in against, or the sign-in stops with an error before anything is printed or opened. A link that sends your browser somewhere other than the client you are signing in to is that client misbehaving, and the CLI does not guess past it. Nothing that is not http or https is ever handed to the opener.

The offer appears only where a key can be pressed. It needs a terminal on stdin, for the key, and on stderr, where the line is written. --json, --no-input, PITHY_NONINTERACTIVE=1, a pipe or redirect on stdin or stderr, --no-open, and PITHY_NO_OPEN set to any non-empty value each suppress the line as well as the open. Redirecting stdout does not, so pithy dashboard connect > connection.json still offers o to the person watching. An opener that is missing — a headless box with no xdg-open — costs one line naming the URL to open yourself, and the sign-in carries on.

Windows offers nothing, deliberately. There is no o on Windows: the URL and the code are printed, and you open the page yourself. Every mechanism available there is either a command interpreter or drops what this URL needs. cmd /c start re-parses its own command line, so &, |, ^, > and %VAR% — all legal in a URL, and this URL arrives over the wire from whatever --origin names — stop being an address and become commands. rundll32 url.dll,FileProtocolHandler strips the query string, and explorer.exe will not open a URL carrying arguments, so both lose the code the page needs. PowerShell works, and it is still an interpreter reading a string somebody else sent. A missing convenience is a paragraph on this page; a shell injection is an incident.

--json

One line, one object, one shape per subcommand. A failure is one {"error": …} line on stderr, with exit, retryable and, where the cause is known, fix, and the process exits by its class.

dashboard.connect

$ pithy dashboard connect --env prod --purpose "Support triage, reading threads and replying." --json
{"command":"dashboard.connect","schemaVersion":2,"environment":"prod","connectionId":"b6a1f0c2-…","issuer":"https://app.pithy.sh","workerUrl":"https://api.example.com","scopes":["manifest:read"],"keyId":"cpk_2026_07","status":"connected","updated":false,"authorizedBy":"ada@example.com","actorKind":"dashboard","purpose":"Support triage, reading threads and replying."}
KeyTypeMeaning
command"dashboard.connect"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment the connection is bound to
connectionIdstringThe connection’s id — the token aud, and the row’s primary key
issuerstringThe management-client origin every token from this connection must carry
workerUrlstringThe Worker URL the management client will call
scopesstring[]The operations granted, as stored on the row
keyIdstring or nullThe key registered by this run, or null when --update only re-pointed
status"connected", "needs_reconnect", "unreachable", "registered" or "awaiting_first_call"Whether a signed ping proved the connection. registered is the --public-key path: written, but nothing proved it; unreachable is a management client that never answered; awaiting_first_call is an --oidc-issuer trust, which nothing can prove until a workload calls
detailstringOperator-facing context for a status that is not connected. Absent otherwise
updatedbooleanTrue when an existing connection was re-pointed rather than a new one created
authorizedBystring or nullWho sanctioned the connection — the signed-in session’s email — or null for one registered before principals were recorded
actorKind"agent", "dashboard", "script" or nullWhat kind of client it is for, or null for one registered before it was recorded
purposestring or nullWhat the client is for, in the registering operator’s words, or null when it was never said
trustobjectThe trust an --oidc-issuer run registered. Absent otherwise
trust.trustIdstringThe trust’s id — what a call names on pithy-control-plane-trust
trust.issuerstringThe iss it accepts
trust.audiencestringThe aud a token must name
trust.claimsobjectWho it admits: every named claim must equal its value
trust.notesstring[]What to read once, such as the trade of matching on a name rather than an id

dashboard.rotate

KeyTypeMeaning
command"dashboard.rotate"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment rotated
connectionIdstringThe connection the key was appended to
keyIdstringThe newly registered key
previousKeyIdsstring[]The keys that were already live, and that stay live. Two live keys is the normal state
status"connected" or "needs_reconnect"Whether a signed ping proved the new key
detailstringOperator-facing context when the ping did not prove it

dashboard.revoke-key

KeyTypeMeaning
command"dashboard.revoke-key"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment the key was revoked on
keyIdstringThe key named by --key-id
revokedbooleanfalse when no key answered to that id. Re-running a revoke is not an error
connectionobject or nullThe connection after the write, or null when nothing matched
connection.idstringThe connection id — a UUID, because it is the token aud and therefore externally exposed
connection.environmentstringThe environment this connection is valid in. Checked against the Worker’s own on every call, so a staging credential cannot reach production
connection.issuerstringThe exact iss this connection accepts
connection.workerUrlstringThe deployed Worker URL captured at connect
connection.basePathstringWhere this Worker mounts the seam
connection.authorizedBystring or nullWho sanctioned the connection, or null for one registered before principals were recorded
connection.actorKind"agent", "dashboard", "script" or nullWhat kind of client it is for, or null
connection.purposestring or nullWhat the client is for, or null
connection.scopesstring[]The operations granted, stored and enforced on your side
connection.keysobject[]Every key this connection may sign with, current and superseded
connection.keys[].keyIdstringThe key’s id, matched against a token’s kid header
connection.keys[].publicKeyobjectThe Ed25519 public JWK
connection.keys[].validFromstringISO-8601. When the key became valid
connection.keys[].validUntilstring or nullISO-8601, or null while open-ended. Set only by the expire route
connection.keys[].revokedAtstring or nullRevocation ignores validUntil and takes effect immediately
connection.trustsobject[]Every OIDC trust the connection honors, live and revoked: trustId, issuer, jwksUrl, audience, claims, authorizedBy, validFrom, revokedAt, firstCallAt. Absent from an older CLI
connection.createdAtstringISO-8601
connection.updatedAtstringISO-8601

connection is the stored row as the CLI decoded it, so every date arrives as an ISO-8601 string rather than the ms-epoch SQLite holds.

dashboard.disconnect

KeyTypeMeaning
command"dashboard.disconnect"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment revoked
connectionIdstring or nullThe connection that was removed, or null when there was nothing registered
removedbooleanWhether a row was deleted. false on a re-run, which is not an error
dashboardNotifiedbooleanWhether the management client was successfully told. Never gates the revocation — --local makes it false by choice
detailstringWhy the management client was not told, when it was not
trustLatencystringWhen the connection held a live trust: a token already minted stays usable until it expires. Absent otherwise

dashboard.revoke-trust

$ pithy dashboard revoke-trust --env prod --trust-id 4b8f0c1e-… --yes --json
{"command":"dashboard.revoke-trust","schemaVersion":1,"environment":"prod","trustId":"4b8f0c1e-…","revoked":true,"latency":"A token cannot be revoked, only the trust. …"}
KeyTypeMeaning
command"dashboard.revoke-trust"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment the trust was revoked on
trustIdstringThe trust named by --trust-id
revokedbooleanfalse when no trust answered to that id. Re-running a revoke is not an error
latencystringWhat a caller should expect from here: a token already minted stays usable until it expires

dashboard.status

KeyTypeMeaning
command"dashboard.status"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentstringThe environment inspected
connectedbooleanWhether anything is registered at all. false is the shipped, denying state
connectionIdstring or nullThe connection’s id
issuerstring or nullThe management-client origin this connection trusts
workerUrlstring or nullThe Worker URL the management client calls
scopesstring[]The operations granted
authorizedBystring or nullWho sanctioned the connection, or null — nothing registered, or registered before principals were recorded
actorKind"agent", "dashboard", "script" or nullWhat kind of client it is for, or null on the same terms
purposestring or nullWhat the client is for, or null on the same terms
keysobject[]Every registered key, live and superseded, in stored order
keys[].keyIdstringThe key’s id, as a token’s kid names it
keys[].livebooleanWhether this key may verify a call right now
keys[].ageDaysnumberWhole days since the key became valid — the number a rotation policy is read against
keys[].validFromstringISO-8601
keys[].validUntilstring or nullISO-8601, or null while open-ended
keys[].revokedAtstring or nullISO-8601, or null
trustsobject[]Every OIDC trust, live and revoked
trusts[].trustIdstringThe trust’s id, as a call names it
trusts[].issuerstringThe iss it accepts
trusts[].audiencestringThe aud a token must name
trusts[].claimsobjectWho it admits — the population, on the face of the listing
trusts[].authorizedBystringWho sanctioned it. Never who may use it
trusts[].state"awaiting_first_call", "called" or "revoked"awaiting_first_call until a call verifies under it
trusts[].validFromstringISO-8601. When it was registered
trusts[].firstCallAtstring or nullISO-8601, or null while awaiting a first call
trusts[].revokedAtstring or nullISO-8601, or null
status"connected", "needs_reconnect" or "unverified"unverified unless --verify was passed. Status never claims a round-trip it did not make
detailstringOperator-facing context from the probe

dashboard.connections

$ pithy dashboard connections --principal ada@example.com --json
{"command":"dashboard.connections","principal":"ada@example.com","byEnvironment":[{"environment":"prod","connections":[{"id":"b6a1f0c2-…","environment":"prod","actorKind":"agent","purpose":"Nightly audit summarizer.","authorizedBy":"ada@example.com","credentialKind":"key","scopes":["manifest:read"],"trusts":[],"live":true,"registeredAt":"2026-10-01T00:00:00.000Z","revokedAt":null}],"unattributed":[]}]}
KeyTypeMeaning
command"dashboard.connections"The subcommand that produced the line
principalstringThe email the connections were matched on
byEnvironmentobject[]Every environment read, in order
byEnvironment[].environmentstringThe environment
byEnvironment[].connectionsobject[]The connections the principal authorized there, in the shape GET /control-plane/connections answers: id, environment, actorKind, purpose, authorizedBy, credentialKind, scopes, trusts, live, registeredAt, revokedAt
byEnvironment[].unattributedobject[]Connections registered before principals were recorded, in the same shape. Never revoked by a principal
revocationsobject[]With --revoke: each connection ended, as environment, connectionId, revokedKeyIds and revokedTrustIds. Absent otherwise

Errors

A needs_reconnect is not an error: the registration succeeded, the round-trip did not, and the command reports both and exits 0.

No Worker resolves the database. Every subcommand opens the registry, so this is the one door the check sits behind.

No worker resolves the DB binding for this environment.
Add the DB d1_databases binding to a worker's wrangler.jsonc, or pass --worker to name one.

Nothing is connected. rotate against an environment with no registration raises controlplane/not_connected, whose action names the pithy dashboard connect --env <environment> that runs as written: no --worker in a project with one Worker, and with several, one command for each Worker that composes controlplane().

The Worker composes no control-plane seam. connect targets the Worker that composes controlplane(), and this one does not, so there is nothing to connect. It is core/precondition_failed, exit 3, and the remedy is an edit, so it names no fix.

<worker> does not compose the control-plane seam, so there is nothing to connect.
Add `controlplane()` to that Worker's pithy.config.ts, deploy, then run connect again.

A confirmation nobody could answer. revoke-key, revoke-trust, disconnect and connections --revoke ask before they act, and the answer they default to is no. So a run that cannot ask — --json, --no-input, PITHY_NONINTERACTIVE=1, no terminal — and did not pass --yes is refused input/required, exit 2, never taken as yes.

$ pithy dashboard revoke-key --env prod --key-id cpk_2026_07 --json
{"error":{"code":"input/required","status":400,"flag":"--yes","message":"Revoke key cpk_2026_07 on prod?","action":"Pass --yes to revoke it without asking.","exit":2,"retryable":false}}

--public-key without --issuer. The issuer is compared on every call, so there is no default to fall back on.

--issuer or --key-id without --public-key. Both are refused rather than ignored: on the dashboard path the client mints the keypair and returns the issuer, so either flag would be a value nothing reads.

No signed-in session. Registering a connection records who authorized it, and only a session names a person. An account token, a session with no email, and no credential at all are each core/precondition_failed, exit 3, in every environment — dev included — and nothing is created anywhere.

Registering a connection takes a signed-in session, not an account token.
Run `pithy cloudflare connect` to sign in as yourself, then run this again. An account token deploys; it registers nothing.

No purpose, and nobody to ask. input/required, naming --purpose. At a terminal it is asked for instead.

Say what this client is for.
Pass --purpose "<what it does>", e.g. --purpose "Support triage, reading threads and replying." It is what a review of this credential reads.

A purpose that cannot be stored. Empty, longer than 200 characters, or carrying a control character, a line break or a bidi override. validation/invalid_input, exit 2.

--public-key or --oidc-issuer without --kind, or --kind without either. The kind is the operator’s to say on those paths and nobody’s to claim on the other: the device-code flow is the dashboard, always.

--public-key needs --kind.
Pass --kind agent for a client acting on its own judgment, or --kind script for automation doing one fixed thing.

A trust with no claim constraint. Refused at registration, because an issuer alone accepts every workload it serves. validation/invalid_input, exit 2.

A trust needs at least one claim constraint. An issuer alone accepts every workload it serves.
Name the workload with at least one --oidc-claim, preferring an immutable id: --oidc-claim repository_id=1262274726.

A trust at a known issuer that names no workload. Its claims describe the job, not whose it is, so anybody the issuer serves could match them. validation/invalid_input, exit 2, before a project is read.

Those claims describe a job, not whose it is, so this trust would admit any GitHub Actions workload that matches them.
Add a claim that names the workload, preferring the immutable id: --oidc-claim repository_id=1262274726.

--scope, --kind or --purpose on a trust joining a connection. They belong to the connection, and a trust takes them as they are. Refused rather than dropped, so a --scope content:read never leaves a workload believed read-only holding the whole grant. validation/invalid_input, exit 2, and nothing is written.

This environment already has a connection, and a trust joins it with its grant, kind and purpose. --scope would be ignored.
Drop --scope. To change what the connection may call, run `pithy dashboard connect` with --env prod, --update and every --scope it should hold — that changes the grant for every credential on the connection.

--oidc-claim or --oidc-audience without --oidc-issuer, or --oidc-issuer beside --public-key or --update. A partial or contradictory set is refused rather than half applied.

--oidc-claim and --oidc-audience only apply with --oidc-issuer.
Pass --oidc-issuer with the exact iss the workload's tokens carry, or drop them.

An issuer that does not resolve. Its discovery document is missing, names another issuer, or points at no key set. core/upstream_failed, and nothing is registered.

--update with nothing to update. Pass --worker-url, --scope, --purpose, or any of them together.

connections --revoke without --reason, or a --principal that is not an email. Each is validation/invalid_input, exit 2, before anything is read. The reason is recorded on every revocation, so there is no default.

A public key that is not an Ed25519 JWK. A file that is not JSON, a P-256 key, and a private key carrying a d component are each refused here rather than written into your authorization row. A key with no id is refused too: every token names its key in the kid header, and a key nobody can address is a key nobody can use.

The management client asked for more than you granted. Nothing is registered.

The sign-in request expired. The device-code flow polls until the authorization’s own expiry and then stops rather than running forever.

The origin could not be reached. A transport failure names the origin and says which of it answered nothing and it answered wrongly happened, so --origin is only suggested where re-checking it would help.

The management client refused the sign-in. A 401 or 403 from the client means the credential was refused, not the request. There is no separate sign-in command: each dashboard command signs in for itself by device code, so the action is to run the same command again and sign in afresh.

Examples

Connect production, choosing the grant at a terminal.

$ pithy dashboard connect --env prod --purpose "Support triage, reading threads and replying."
acme-api → https://api.example.com/control-plane (declared in pithy.config.ts)
Open https://app.pithy.sh/connect?userCode=WXYZ-1234 to approve.
Check that the page shows WXYZ-1234.
Press o to open the link in the browser.
▸ Waiting for approval...
Connected prod.
Connection     b6a1f0c2-…
Issuer         https://app.pithy.sh
Worker         https://api.example.com
Scopes         manifest:read, keys:rotate, migrations:read, privacy:read, evidence:read, processing:read, erasure:read, retention:read, auth:users:read, audit:events:read, email:jobs:read
Key            cpk_2026_07
Authorized by  ada@example.com
Kind           dashboard
Purpose        Support triage, reading threads and replying.
Done.

The reads come from what that Worker composes. email:jobs:retry and auth:sessions:revoke are declared on the same capabilities and are not there — they are writes.

Rotate, and read the line that is the point of the command.

$ pithy dashboard rotate --env prod
Rotated prod. New key cpk_2026_08.
cpk_2026_07 is still live. Expire it from your management client once it has proven cpk_2026_08.
Done.

Trust a GitHub Actions workflow, with no key to place.

$ pithy dashboard connect --env prod --oidc-issuer https://token.actions.githubusercontent.com --oidc-claim repository_id=1262274726 --oidc-claim environment=prod --kind agent --purpose "Nightly audit summarizer."
acme-api → https://api.example.com/control-plane (declared in pithy.config.ts)
Registered prod. Awaiting a first call.
Connection     b6a1f0c2-…
Worker         https://api.example.com
Scopes         manifest:read, keys:rotate, audit:events:read
Trust          4b8f0c1e-…
Issuer         https://token.actions.githubusercontent.com
Audience       https://api.example.com
Admits         repository_id=1262274726, environment=prod
Authorized by  ada@example.com
Kind           agent
Purpose        Nightly audit summarizer.
No key to place. The workload calls with its own token on pithy-control-plane-oidc, naming this trust on pithy-control-plane-trust and one scope on pithy-control-plane-scope.
Done.
pithy dashboard connect --env prod --update --worker-url https://api.example.com
pithy dashboard connect --env prod --update --purpose "The hosted dashboard, for billing support."
pithy dashboard connect --env prod --public-key ./client.jwk.json --issuer https://admin.example.com --kind script --purpose "Nightly refund report." --scope manifest:read
pithy dashboard revoke-key --env prod --key-id cpk_2026_07 --yes
pithy dashboard revoke-trust --env prod --trust-id 4b8f0c1e-… --yes
pithy dashboard status --env prod --verify
pithy dashboard disconnect --env prod --yes --local
ESC