surge

Install the Surge command-line interface globally using npm to enable static web publishing from your terminal.

npm install -g surge

To publish a static website, run the surge command followed by the directory path you want to deploy and your desired subdomain.

Example: surge <directory> <subdomain>.surge.sh

surge . hello.surge.sh

When initializing the surge function, you can provide a configuration object with the following keys:

• endpoint: The base URL for the Surge API (defaults to https://surge.surge.sh).
• platform: The platform name used to construct the default endpoint (defaults to surge.sh).
• name: The name used for CLI/output branding (defaults to surge).

When applying SSL/TLS certificates via Surge, the process may abort due to authorization or credential issues. The middleware handles specific HTTP status codes from the Surge API:

• 403 Forbidden: The request was aborted. This occurs if you are unauthorized to apply SSL to the specific req.domain. If the response includes a reason header, that reason will be displayed.
• 401 Unauthorized: The local token has expired. The middleware will attempt to clear the local credentials for the current endpoint. You should try logging in again to refresh your token.

If an error occurs during the handshake process, the error details are logged to the console.

When interacting with the Surge configuration via the SDK, errors may occur during the sdk.settings call. The system handles two types of error structures:

1. Single message error: If the error object contains a message property, it is displayed as Error - <message>.
2. Multiple message error: If the error object contains a messages array, each message is iterated and displayed as Error - <message>.

In both cases, the process will exit with code 1 upon encountering a configuration error.

The stats namespace provides usage and traffic metrics for a project. It supports the following verbs:

• traffic
• load
• audience
• usage

The publish command is used to upload a directory to a Surge domain. It supports various lifecycle hooks for customization.

Available hooks for publish:

• preAuth, postAuth
• preProject, postProject
• preDomain, postDomain
• preSize, postSize
• prePublish, postPublish

Most Surge command functions (e.g., surge.publish, surge.login, surge.token) accept an optional hooks object. This allows you to inject custom logic at various stages of the command lifecycle.

Common hook names include:

• preAuth / postAuth: Executed before and after authentication checks.
• preProject / postProject: Executed around project discovery/resolution.
• preDomain / postDomain: Executed around domain resolution.
• prePublish / postPublish: Executed around the publishing process.
• preSize / postSize: Executed around file size calculations.
• preEncrypt / postEncrypt: Executed around encryption tasks.

The debug namespace provides diagnostic information for a project. It supports the following verbs:

• status
• files
• audit
• bust
• certs
• encrypt

The dns namespace provides tools for managing DNS records for a project. It follows the pattern surge <project> dns <verb> or surge dns <verb> for the current directory.

Supported verbs:

• list / all: List DNS records.
• add: Add a record.
• rem: Remove a record.