surge: the CLI that publishes a static folder to a URL in one command

What surge publishes, and what it refuses to publish

surge is a command line tool that takes a directory of already-built files and puts it on the web at a domain you name. The README describes it as "static web publishing" and the package keywords include static, deploy, publish, hosting, cdn and jamstack. That is the whole scope. There is no build step, no server runtime, no database and no serverless function layer described anywhere in the README. If your output is a folder of HTML, CSS, JavaScript and assets, surge is aimed at you. If your output needs a process running on the other end, it is not.

The intended user is a frontend developer who has just run a build and wants a URL, or a CI job that does the same thing without a human. The README also positions the tool for programmatic use, stating that every feature available in the CLI is accessible via the API, which it frames as suitable for automated pipelines and agent-driven workflows. That claim is about the platform, not the CLI package, and the README does not document the API endpoints themselves.

The package description in package.json is simply "Static Web Publishing", and the binary is exposed as ./bin/surge. There is no library entry point promised for embedding, although main points at ./lib/surge.js.

Two arguments, one upload, and a CDN that answers on a real domain

The mechanism the README shows is short. You give surge a path and a domain, and it uploads the contents of that path and serves them from the domain you chose. The README's example publishes ./dist to lucid-example.surge.sh, and the result line states the project is live in 10 regions globally and viewable at https://lucid-example.surge.sh. The introduction makes the larger claim of over 14 million deployments across 10 regions, which is the platform's figure rather than something the CLI measures.

The dependency list is where the actual shape of the tool is visible. surge-sdk and surge-stream are the two packages that carry the deployment protocol, both pinned at 0.20.0. surge-ignore and ignore handle which files get excluded from the upload, so the tool has its own ignore semantics rather than only reading .gitignore. netrc is present, which points at credential storage on disk. is-domain and url-parse-as-address validate and interpret the domain argument before anything is sent. moniker generates names, and the release notes for v0.19.0 describe an underscore helper for random subdomain, which is the feature that lets you publish without choosing a domain at all.

What the README does not describe is what happens on a second publish to the same domain, whether old files are deleted or merely shadowed, or how a partial upload is rolled back. Those are the questions that decide whether surge is safe in a production pipeline, and the README is silent on all of them.

Installing surge and publishing a first folder

The README gives exactly one install command, a global npm install. The package engines field requires Node >=18.13, so check your Node version before installing, because an older runtime will fail the engine constraint rather than degrade gracefully.

npm install -g surge

After that, the README's publish step takes a path and a domain as two positional arguments. The path is a directory on disk, and the domain is the hostname you want the files served from.

surge <path> <domain>

The README's own worked example substitutes a build output directory and a subdomain under surge.sh.

surge ./dist lucid-example.surge.sh

According to the README, the command reports that the project is live in 10 regions and prints the URL, in that example https://lucid-example.surge.sh. The first run is also where authentication happens: the README shows a surge-help screenshot but does not spell out the login flow, and the netrc dependency suggests credentials land in a netrc file on your machine. If you are running this in CI, that is the part to plan for, because an interactive prompt in a pipeline will hang rather than fail loudly.

Where surge stops being the right tool

The clearest limitation is in the name. surge publishes static content. Anything that needs to run on request, hold state, or terminate a websocket is outside what the README claims, and the README does not mention a functions, workers or server-side feature to fill that gap. A team building an API should not start here.

The second limitation is documentation depth. The README covers install and publish, and then stops. It does not document rollback, cache invalidation, custom headers, redirects, environment-specific configuration, team access, or how to remove a deployment. For a tool whose pitch includes CI/CD integration, the absence of a documented non-interactive credential path is a real gap: netrc appears in the dependency list, but the README never explains how to write it or whether a token can be passed by environment variable.

The third is versioning. The most recent release listed in the repository is v0.19.0 from 2017, while package.json carries version 0.44.3, and the last push to the repository was on 2026-09-18. That combination is worth reading carefully: the code is being touched, but the release notes in the repository do not reflect the version actually shipped on npm. Anyone who needs a changelog to decide whether to upgrade will not find one that matches the installed package.

surge against Netlify CLI and Vercel CLI

The nearest alternatives are the Netlify and Vercel command line tools. The difference in approach is not the upload, it is what sits behind it. Netlify CLI and Vercel CLI both assume a project configuration file and a build step that the platform runs for you, and both extend into serverless functions and edge middleware. surge assumes you have already built the folder and hands the CDN the result. That makes surge smaller to reason about: there is no build image to match, no framework detection to fight, and no platform-specific config file to keep in sync with your app.

It also makes surge narrower. A project that needs a form handler, an authenticated API route or a scheduled job will outgrow it. The trade is roughly this: surge asks you to bring your own build and gives you a URL, while the alternatives ask you to adopt their build and give you a platform. If your build already runs in CI and you only need somewhere to put the artifacts, the extra machinery in the alternatives is overhead. If you do not have a build pipeline yet, surge will not build one for you.

Licence, maintenance and the cost of upgrading

The README ends with a licence section stating copyright 2012-2026 Chloi Inc. and release under the ISC License, and it notes that "Surge" is a trademark of Chloi Inc. The package.json agrees, carrying "license": "ISC". The repository metadata supplied here lists the licence as unknown, so the two sources disagree; anyone who needs certainty for compliance should read the LICENSE file in the repository rather than either summary. ISC is a permissive licence in the same family as MIT, but that is a description, not legal advice.

The upgrade cost is the interesting part. package.json pins most dependencies to exact versions, including surge-sdk and surge-stream at 0.20.0, and adds overrides for diff at 8.0.3 and serialize-javascript at 7.0.7. Exact pins make installs reproducible and make dependency bumps a deliberate act rather than a surprise. The engine floor of Node >=18.13 is the constraint that will bite first: a machine on an older LTS cannot install the current package at all.

The version script in package.json runs npm publish as part of npm version, and postversion pushes to origin with --no-verify, which skips git hooks. That is a maintainer convenience and a reason to trust the published tarball over the repository state when the two differ. The preversion script runs npm test, so a release is gated on the test suite, which uses mocha with nixt for CLI-level tests.

Editorial conclusion

surge fits a frontend developer or CI job that needs to push a built static directory to a public URL without touching a hosting dashboard, and it is a poor fit for anything that needs server-side code, since the README describes a static publishing tool. Before adopting it, check the licence file, since the README states ISC while the repository metadata does not, and run surge --help against the version you install rather than trusting the two commands in the README.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sintaxi/surge on GitHub