Command Reference

The complete surge command surface. Run surge --help for the built-in version of this list; every command also accepts --help.

Project commands are written here as surge <domain> <verb>, but the target slot takes three forms: a domain, a path to a project directory, or nothing at all—in which case the current directory's project is the target. surge example.com rollback, surge ./dist rollback, and surge rollback are the same command. Account commands take no target.

Commands typed in the older, verb-first order (surge rollback example.com) keep working forever; the CLI answers and prints the current spelling in grey. A few commands are deliberately absent from --help—zone, ssl, token, and the specific-revision forms—power tools the help screen doesn't spend lines on; this page documents everything. surge account <verb> also dispatches to the flat identity commands (surge account whoami = surge whoami), silently.

Global flags

Flag	Alias	Description
`--project <path>`	`-p`	The directory to publish. Also settable as the first positional argument.
`--domain <domain>`	`-d`	The domain to act on. Also settable as a positional argument or via the `CNAME` file.
`--preview`	`--stage`, `-s`	Publish a preview instead of cutting over production.
`--message <msg>`	`-m`	Attach a message to the revision (or to a token at `tokens add`).
`--add <email>`	`-a`	Add a collaborator during publish.
`--remove <email>`	`-r`	Remove a collaborator during publish.
`--token <token>`		Authenticate with a token instead of the stored login. The `SURGE_TOKEN` environment variable does the same.
`--endpoint <url>`	`-e`	Target a different Surge API endpoint.
`--version`	`-V`	Print the CLI version.
`--help`	`-h`	Print the command listing, adapted to the target.

Publish-intent flags carry their own routing: surge ./dist -d example.com and bare surge --preview are publishes, no verb needed.

Publishing

`surge <path> <domain>`

Publish a directory to a domain. Pass _ as the domain for a freshly generated .surge.sh subdomain, no prompt. Prefix the domain with https:// to force HTTPS redirects for the project. Respects .surgeignore. → Publishing

`surge [path] publish`

Publish using the project's own domain—from its CNAME file when present, prompting with a generated suggestion otherwise (enter _ at the prompt for a fresh one). This is the everyday form once a project knows where it lives. deploy is accepted as a silent alias.

`surge <domain> teardown`

Remove the project from the domain and the CDN. → Revisions

Revisions

`surge list`

Every project on your account, with age, tooling, and plan.

`surge <domain> revs`

The project's revisions—preview URL, age, author, size, and message—with the live revision highlighted. → Revisions

`surge <domain> rollback`

Serve the previous revision.

`surge <domain> rollfore`

Serve the next revision (the inverse of rollback).

`surge <domain> cutover [revision]`

Serve the latest revision, or the given one. Ships previews.

`surge <domain> discard [revision]`

Remove a revision from the system. If it was live, production moves to a neighboring revision; discarding the last revision takes the project offline.

Domains & DNS

`surge <domain> dns list`

List the domain's custom DNS records. Bare dns prints the available subcommands and Surge's name servers. → Domains & DNS

`surge <domain> dns add <type> <name> <value>`

Add a DNS record. MX records take a priority: dns add MX <priority> <value> (host defaults to @) or dns add MX <name> <priority> <value>.

`surge <domain> dns rem <id>`

Remove a DNS record by the id shown in the listing.

`surge <domain> zone`

Print the domain's complete zone in BIND format, including records Surge manages automatically. Supports the same add/rem subcommands as dns.

Debug

`surge <domain> debug status`

The domain's state: waiting on dns (with the records to add), securing, or live. → Analytics & Diagnostics

`surge <domain> debug files`

List every file in the live revision with its size, as served by the CDN.

`surge <domain> debug audit`

Report each edge node's state for the domain: revision, file count, size, certificate validity.

`surge <domain> debug bust`

Purge the project from the cache on all edge nodes.

`surge <domain> debug certs`

Show the certificates installed for the domain: subject, issuer, alt names, expiry, auto-renewal. → SSL Certificates

`surge <domain> debug encrypt`

Provision the domain's managed SSL certificate manually. Certificates normally provision and renew automatically.

Stats

`surge <domain> stats traffic`

Visits, uniques, connections, encryption share, cache hit rates, top pages, 404s, redirects, and sources for the past two weeks. → Analytics & Diagnostics

`surge <domain> stats audience`

Browsers, operating systems, and devices of your visitors.

`surge <domain> stats usage`

Per-file bandwidth served, with a projected monthly total.

`surge <domain> stats load`

Connection volume per datacenter across the network.

Configuration

`surge <domain> config`

View the project's platform settings; pass flags to change them: --force http|https, --redirect <domain>, --cors <domain>|*, --cache strict|casual, --hsts <seconds>, --ttl <seconds>, any value null to clear. Changes apply across the edge immediately. → Project Configuration

Collaborators

`surge <domain> invite <emails…>`

Invite one or more people to publish to the project. → Collaborators

`surge <domain> revoke <emails…>`

Revoke publishing rights immediately.

SSL

`surge <domain> ssl --pem <file>`

Upload a custom certificate as a PEM bundle (cert + intermediates + key). Validated before being applied. Paid plans. Managed certificates need no command at all—see SSL Certificates.

Account

`surge login`

Authenticate (or create an account) and store a token in ~/.netrc. → Account, Plans & Tokens

`surge logout`

Remove the stored token and expire it.

`surge whoami`

Show the logged-in email and plan.

`surge verify`

Send an email verification link to your address.

`surge login --browser`

`surge mfa`

Open the browser page that sets up or manages two-factor auth. → Account, Plans & Tokens

`surge tokens list`

Every token on the account: id, scope, message, uses, created, last used. → Tokens

`surge tokens add [--domain <domain>] [-m <msg>]`

Mint a token—shown once, at mint time. --domain scopes it to one domain; -m labels it.

`surge tokens rem <id>`

Expire a token by its tok- id.

`surge token`

Print the token the CLI is currently authenticating with.

`surge plan [--web | --manage]`

Change your account plan interactively, or print a private browser link for checkout (--web) or full billing management (--manage).

`surge card`

Update the payment card on file.

`surge nuke`

Permanently delete your account. Requires all projects to be torn down first.