Account, Plans & Tokens

Your Surge account is created and managed entirely from the CLI. The account commands take no target—they're about who's typing, not any particular project—so they all sit at the top level.

login

surge login

Prompts for email and password. If the email has no account yet, one is created—login and signup are the same step. On success, a token is stored in your ~/.netrc file (readable only by you), and every subsequent command uses it silently.

Mistype your password three times and the CLI offers to email you reset instructions.

Sign in with the browser

surge login --browser

Instead of a password prompt, the CLI prints a link and a four-letter code, opens your browser, and waits. Sign in on the page—with Google, GitHub, or your email and password—check that the code on the screen matches your terminal, and approve. The CLI picks up the token and stores it exactly as a password login would.

Nothing about the stored session differs between the two: same ~/.netrc entry, same token, same surge logout. It works over SSH too—the link opens on any browser, anywhere. Accounts with two-factor auth on sign in this way.

logout

surge logout

Removes the session's token from ~/.netrc and expires it, so it can never be used again—by you or anything that saw it. Log in again to mint a fresh one.

whoami

$ surge whoami

   you@example.com - Free

Shows the logged-in account and its plan. Handy in CI to confirm which account a token belongs to.

verify

surge verify

Sends a verification link to your account's email address. Verifying matters: unverified accounts publish under reduced rate limits.

mfa

surge mfa

Two-factor auth for your account. The command opens a page in your browser and gets out of the way—setup and management both happen there, so no secret, code, or recovery code ever passes through a terminal.

Turning it on: sign in fresh on the page, add the key it shows to your authenticator app, confirm with a code, and save the ten recovery codes—each signs you in once if you lose your authenticator, and they're shown exactly once.

With two-factor on:

  • Your password alone signs nothing in. surge login points you at surge login --browser, where the sign-in page asks for your code after your password. Google and GitHub sign-in carry their own second factor and work as before.
  • Tokens are untouched. CI, scripts, and agents holding a token keep working—two-factor guards the ceremonies that create credentials, never the credentials themselves.
  • Turning it off happens on the same page (surge mfa again) and requires a current code or a recovery code.

tokens

A token lets anything that isn't you—a CI pipeline, a script, an agent—publish as your account. Mint one per use, label it, and scope it to just the domain it needs:

surge tokens list                              # every token: id, scope, msg, uses, last used
surge tokens add [--domain <domain>] [-m <msg>]  # mint a token
surge tokens rem <id>                          # expire a token

$ surge tokens add --domain lucid-example.surge.sh -m "github actions"

   f3a1c98c42d76c1ba9d3a9f4e3c0ffee

   Scoped to lucid-example.surge.sh — github actions

The token itself is shown once, at mint time—copy it then. Everywhere else it's represented by its id (tok-1a2b3c4d), which is what tokens list shows and tokens rem takes. A token minted with --domain can publish only to that domain; without it, the token has full account access. The -m message is how you remember what a token is for, and the uses and last used columns tell you whether it's still earning its keep.

See CI & Automation for putting tokens to work.

plan

surge plan

Shows the available plans with pricing and perks, and lets you switch with an interactive picker—upgrade or downgrade at any time. Card entry happens inline the first time a paid plan needs one.

Prefer the browser for anything billing-related:

surge plan --web       # upgrade via browser checkout
surge plan --manage    # manage plan, card & invoices in the browser

Both print a private link (valid 48 hours) that opens a secure billing page.

card

surge card

Updates the payment card on file.

nuke

surge nuke

Permanently deletes your account. All projects must be torn down first—the command refuses while any remain. There is no undo.