Illustration showing the logo is a free static website host which you interact with from your command line. It makes it quick and easy to get new sites and apps online, either manually or as part of your CI build process. Here’s how to get started using the service.

First Run

We’ll assume you’ve already got a directory of files you want to deploy to the web. If you haven’t, create a new folder, add an index.html, and some simple starter content.

Surge’s binary is a JavaScript application distributed via npm. Make sure you’ve got Node.js installed on your system before you continue. Begin by using npm to install Surge:

npm install --global surge

Installing Surge globally means you can use the surge command anywhere, even if your working directory lacks a package.json file. Omitting the --global flag will add the package as a project dependency instead, letting you lock the Surge version used for individual sites.

Now change directory into your website’s repository. Run the surge command to start the deployment process. A series of interactive prompts will be displayed, starting with your email address to setup a Surge account.

Next, confirm the filesystem path to your project. This defaults to your working directory so you can usually press return to continue.

The following prompt asks for a domain name. A random subdomain is selected automatically. You can choose a different subdomain, or one of your own domains, by entering it here. If you’re using your own domain, the following sections explain how to finish setting it up.

image of deploying a static website with

After you’ve supplied a domain name, press enter to begin the deployment. The progress will be displayed in your terminal as the Surge CLI uploads your files and makes them available on the web. Visit your domain in your browser to see your content live!

Site updates are applied by running the surge command again. The contents of your project directory will be synced up to your live website.

Everything in your folder is uploaded by default. You can exclude specific paths by creating a .surgeignore file. This has the same syntax as .gitignore. Files and folders commonly created by other developer tools, such as Git and npm, are automatically omitted.

Using Your Own Domain Name

Surge offers custom domain support via CNAME records. This comes at no extra cost over the standard service. Add a CNAME record in your domain provider’s control panel. Point the @ and www hostnames to Supply your domain name when running surge to deploy your site.

You’ll be prompted for your domain each time you run the surge command. You can avoid this by adding the --domain flag to surge commands. Alternatively, create a CNAME file in your project directory. Write your domain name into this file.

surge --domain

echo "" > CNAME

Managing HTTPS Redirects

Surge has automatic HTTPS support but this does not handle HTTP to HTTPS redirects by default. Explicitly deploy to the https variant of your domain to force all visitors to use a secured connection. Enabling redirects is advisable for all publicly accessible websites.

surge --domain

You’ll need to supply an SSL certificate if you’re using your own domain. This feature is only available as part of the paid Surge Plus plan.

Surge also gives you control of bare domain to www redirects. The default behavior sees redirect to You can reverse this by explicitly including the www portion in your deployment domain.

surge --domain

Configuring Your Site

Surge offers several built-in convenience functions which help it stand out against other similar platforms. You can add a 404 page, password protection, and CORS support, all using special files in your project.

The 404 page is enabled by creating a 404.html file. That’s all there is to it – Surge will serve the file when there’s no direct match for the requested URI.

Password protection is enabled by an AUTH file. This accepts a simple list of usernames and passwords.


You’ll be prompted to enter a username and password using HTTP Basic Authentication each time you access your site. This feature is only available on the paid Surge Plus plan.

Another Surge Plus feature is manual routing rules. You can create a ROUTER file to define custom redirects, either within your site or externally.

301 /moved-page /new-link

Surge supports 301 (moved permanently) and 307 (moved temporarily) status codes for the first column. The last column can be a relative link within your site, or an absolute link to another domain (

One final configuration file is CORS. This lets you permit cross-origin access to your site. Add a * to the file to accept cross-origin requests from any origin. You can write individual domains instead to limit the allowed origins.

Automating Surge Deployments

Surge is entirely controlled by text files and terminal commands. It’s easy to integrate into CI pipelines to deploy websites automatically on each commit.

Automating Surge requires use of API tokens. This lets you avoid the interactive login prompts. First, login to Surge on your development machine. Run surge token to get your API token.

In your CI pipeline, set the SURGE_LOGIN and SURGE_TOKEN environment variables. The former should be your email address while the latter takes your API token. Now you can deploy non-interactively using the --project and --domain flags:

surge --project $PWD --domain


Surge makes it simple to get static websites live on the web. The basic service is free to use. Upgrading to the Plus plan gives you authentication, redirects and more configurable HTTPS.

Unlike other contenders, Surge is fully terminal-driven. This makes it ideal for quick developer-centric sites managed via Git repositories and CI pipelines. It cuts out the server configuration so you can focus on building your site’s content.

For more advanced use cases, Surge even lets you add multiple contributors. Run surge --add to give friends, guests, and colleagues access to your site. They’ll be able to deploy by running surge and supplying the same domain name you’ve been using.

Profile Photo for James Walker James Walker
James Walker is a contributor to How-To Geek DevOps. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker, and Kubernetes.
Read Full Bio »