pithy dashboard connect --env prodYou run this, against your own project. It is the moment you grant a management client the right to call your Worker’s administrative routes — and until you run it, every one of them answers controlplane/not_connected.
Before you run it
Compose the seam, on the Worker that serves your app’s data:
pithy add controlplaneThat opens nothing. It composes a capability that is present and denying.
A deployed environment needs credentials, because the connection row is written into that environment’s real D1 over the REST API. --env dev resolves from local state and needs no account credential for the database, which makes it the right place to try this first.
Sign in as yourself first, in every environment, dev included. A connection records who authorized it, and only a signed-in session names a person: pithy cloudflare connect keeps one for the directory, and connect records its email. An account token, a session with no email, or no credential at all is refused before anything is written. An account token deploys; it registers nothing.
Say what the client is for. --purpose "<what it does>", or answer the question at a terminal. One line of plain text, 200 characters at most. It is what a review of this credential reads, and a run that cannot ask and was given none is refused.
A deploy reminds you. When a staging or production pithy deploy succeeds and the environment has no connection, it names this command, with --env and --worker filled in, on the line before Done. — and under --json as offers, which an agent puts to you rather than running. The Claude Code plugin’s /deploy asks the same question, and on your yes runs this command and hands you the sign-in address and code.
What happens, in order
Your session and the purpose are settled before any of this — before the browser approval, before the management client records anything — so a refusal of either changes nothing anywhere.
sequenceDiagram
autonumber
actor You
participant CLI as pithy CLI
participant Client as Management client
participant D1 as Your D1
participant Worker as Your Worker
CLI->>CLI: Resolve the address from your project
Note over CLI: Printed before anything is registered
CLI-->>You: Every operation your Worker exposes
You->>CLI: The grant you chose
CLI->>Client: Start the device-code flow
You->>Client: Your browser, your approval
Client->>Client: Generate the keypair, keep the private half
Client-->>CLI: The public half, and the granted scopes
CLI->>D1: Write the public key
Client->>Worker: Signed ping
Worker-->>Client: Round-trips
Note over CLI,Worker: Only now does it say Connected
- The address is resolved from your project. The Worker’s domain declaration for that environment, then its route, then a hand-set base URL var. It prints what it found and where it came from before registering anything.
- You choose the grant. At a terminal, a list of every operation your Worker exposes, described in each capability’s own words, preselected to the default. Connection scopes is what the default is and why.
- A device-code flow starts. A short user code, your browser, your approval. The same shape as
wrangler login, and this leg is genuine user delegation — which is why a browser flow belongs here rather than on the machine-to-machine leg. - The client generates the keypair and keeps the private half. The public half comes back.
- The CLI writes it into your D1. This is the one key the CLI ever writes.
- A signed ping round-trips against your Worker.
Nothing reports connected until step 6
That is the part worth understanding, because it is the difference between this and a registration form.
A row written into your database proves that a row was written. It does not prove that the client can reach your Worker, that the address resolved to the right place, or that the base path is where the seam actually mounts.
A registration that was written but cannot be reached is a dead link, and reporting it as connected is how somebody finds out weeks later — when a pane fails and nobody can say when it started.
So a registration whose ping does not round-trip is reported as needs_reconnect, and the command deliberately does not print Done.
The approval page
The link the CLI prints is the dashboard’s /connect with the code already in it, and the line under it prints the code by itself so you can check the page shows the same one. Press o to open it, or paste the link into a browser on another machine. On macOS and Linux o opens your browser; Windows prints the link and opens nothing.
The earlier reasoning against a one-click link said it puts a live credential into a browser history, a chat log, and every proxy between here and there. Two thirds of that is not true over HTTPS: the path and query are encrypted, so no proxy sees it, and a chat log holds it only if somebody pastes it — which is the act the link removes. What survives is the browser history on the machine whose CLI asked, and the dashboard’s own access log.
The code is still displayed. Comparing it against your terminal is the basis on which you approve; the link removes the typing, not the check. The page also counts down to the expiry rather than failing on submit, and offers deny beside approve rather than under it — at one gap the last account and the approval read as one column of equal choices, and the control reached by habit is the one that grants a credential.
- One account is stated. Several are a picker, and the one you pick looks picked. None says so, and points at the way to get one.
- It renders nothing about the machine that started the flow. Everything known about it arrived from an unauthenticated caller, so a hostname here would dress up an attacker’s input as corroboration.
- An expired, unknown or already-decided code is one answer. The page invents no distinction the server refused to make.
- Signed out, the code rides along on the sign-in address, so a sign-in comes back to the same code. Nothing is kept in the browser.
What a successful run looks like
$ 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.
▸ 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 first line is the resolution, printed before anything is registered so you can stop if it names the wrong address.
The last three lines are on your row now. Authorized by is your session’s email, derived and never typed. Kind is dashboard on this path, always, and your Worker stamps it onto every control-plane audit row the connection’s calls write, so a row can tell the dashboard from an agent or a script. Purpose is your words.
The client’s answer is checked, not trusted
A scope the client 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.
That check exists because the client is the one that generates the keypair, and a client that can influence its own grant during that exchange has more power than the design intends.
Re-pointing an existing connection
An address changes — a custom domain, a renamed Worker, a moved environment. The repair is a re-point rather than a rebuild:
pithy dashboard connect --env prod --update --worker-url https://api.example.com--update with nothing to update is refused, naming what it accepts. On an update, passing no scope means leave the grant alone rather than reset it — and because --update replaces the grant when you do pass scopes, a shorter list is already a narrowing command. --scope all asks for every declared scope in one word.
--update --purpose changes what the connection says it is for, and records controlplane/connection_updated with the old value and the new. Who authorized it and its kind are facts of the registration: registering again is the only way to change them. A connection registered before these were recorded keeps working, and pithy dashboard status shows it as registered before principals were recorded.
If it fails
No signed-in session. core/precondition_failed, exit 3, naming pithy cloudflare connect. Sign in as yourself and run it again. Nothing was created anywhere.
The origin could not be reached. The refusal names the origin and says which of it answered nothing and it answered wrongly happened — so the override flag is only suggested where re-checking it would help.
The sign-in request expired. The flow polls until the authorization’s own expiry and then stops rather than running forever. Run it again.
Several Workers, none named. The administrative surface belongs on one Worker per project, and connect refuses the ambiguity rather than guessing. A Worker composing no seam is refused outright.
needs_reconnect. The row is written and the ping did not come back. Check the address the first line printed, and whether that environment is actually deployed.