deplo.ai/docs

Authentication

The CLI authenticates with a long-lived deplo token. You get one via a browser hand-off (the default), by pasting one from Settings, or from the DEPLO_TOKEN environment variable in CI. Provider credentials are never involved — they stay encrypted server-side.

Browser hand-off (default)#

deplo login gets a token without you ever seeing or copying it. The flow is deliberately boring and auditable:

  1. The CLI opens a loopback listener

    An HTTP listener starts on 127.0.0.1 on a random port. It is bound to the loopback interface only — it is never reachable from the network.

  2. Your browser opens the authorization page

    The CLI opens https://www.deplo.in/cli-auth?port=…&state=…&host=… — the port of the listener, a random one-time state nonce generated by the CLI, and your machine's hostname so the page can show which machine is asking.

  3. You explicitly authorize

    Nothing happens automatically. The page shows the request and you click Authorize (signing in with GitHub first if needed). Only then is a CLI token created for your account.

  4. The token travels only to 127.0.0.1

    The page redirects to 127.0.0.1:<port>/callback with the token and the state nonce. The CLI rejects the response unless the nonce matches the one it generated and the token has the dpl_ prefix — a response from anywhere else, or with the wrong nonce, is discarded.

  5. Verify and store

    The CLI verifies the token against the API (/auth/me) and writes it to ~/.config/deplo/config.json with file mode 0600, then prints:

    text
    ✓ signed in patrickdev · token saved to /Users/patrick/.config/deplo/config.json

The whole hand-off times out after five minutes with Timed out waiting for the browser (5 minutes). Try `deplo login --token` instead.

Pasting a token (headless machines)#

On SSH boxes, containers, or anywhere without a browser, create a token manually at deplo.in → Settings → CLI tokens and paste it:

terminal
$ deplo login --token
? Paste your deplo CLI token (dpl_…) › ********
✓ signed in patrickdev · token saved to /home/patrick/.config/deplo/config.json

The prompt is masked. You can also pass the token inline — deplo login --token dpl_… — but prefer the prompt so the token stays out of your shell history. A rejected token prints ✗ that token was not accepted — create a new one at deplo.in → Settings → CLI tokens and exits with code 1.

DEPLO_TOKEN for CI#

In pipelines, skip login entirely: set the DEPLO_TOKEN environment variable. It takes precedence over the config file, so nothing is written to disk. See CI Usage for a full GitHub Actions example.

Token properties#

PropertyBehavior
dpl_ prefixAll CLI tokens start with dpl_, so they are recognizable in configs and never confused with JWTs.
Shown onceThe raw token is displayed exactly once at creation. Lose it and you create a new one.
Hashed server-sideOnly a SHA-256 hash is stored on the platform — the raw token cannot be recovered from a breach.
RevocableDelete any token at Settings → CLI tokens; it stops working immediately.
lastUsedAtEach use stamps the token, so Settings shows you which tokens are actually active.

Logout vs. revoke#

  • deplo logout deletes ~/.config/deplo/config.json — the token is removed from this machine, but remains valid anywhere else it is stored.
  • Revoking at deplo.in → Settings → CLI tokens kills the token everywhere, instantly. Do both when decommissioning a machine; the CLI reminds you:
text
$ deplo logout
✓ signed out — token removed from this machine
  revoke it fully at deplo.in → Settings → CLI tokens
Security model
The token grants the same access as your dashboard session — treat it like a password. It only ever travels over HTTPS to the deplo API and, during login, over the local loopback interface. The CLI never sees your Vercel token or Render API key: those are connected once via deplo connect, validated, and stored AES-256-GCM encrypted server-side. If a token leaks, revoke it in Settings — lastUsedAt tells you if it was used.