Authentication & User Management

Core authentication functionality for managing user credentials and account access. All publishing operations require authentication.

Capabilities

Login

Authenticate with Surge platform and store credentials locally for subsequent commands.

/**
 * Authenticate user with email/password and store credentials
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function login(hooks?: HookConfig): CommandFunction;

CLI Usage:

surge login

Interactive prompts for email and password. Credentials are stored in .netrc format for automatic authentication in future commands.

Library Usage:

const surge = require('surge')();
surge.login({})(process.argv.slice(2));

Logout

Remove stored authentication credentials and expire the current session.

/**
 * Remove stored credentials and expire session
 * @param hooks - Optional lifecycle hooks  
 * @returns Command function
 */
function logout(hooks?: HookConfig): CommandFunction;

CLI Usage:

surge logout

Library Usage:

surge.logout({})(process.argv.slice(2));

Who Am I

Display information about the currently authenticated user.

/**
 * Display current authenticated user information
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function whoami(hooks?: HookConfig): CommandFunction;

CLI Usage:

surge whoami

Displays the email address and account plan of the currently authenticated user.

Library Usage:

surge.whoami({})(process.argv.slice(2));

API Token

Generate an API token for automation and CI/CD integration.

/**
 * Generate API token for programmatic access
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function token(hooks?: HookConfig): CommandFunction;

CLI Usage:

surge token

Generates and displays an API token that can be used for automated deployments. Store in environment variable SURGE_TOKEN for CI/CD systems.

Library Usage:

surge.token({})(process.argv.slice(2));

Environment Variables

Authentication Environment Variables

• SURGE_TOKEN: API token for non-interactive authentication
• TRAVIS_SURGE_TOKEN: Legacy Travis CI integration token

Usage Example:

export SURGE_TOKEN="your-api-token-here"
surge publish ./build example.surge.sh

Credential Storage

Surge stores authentication credentials in .netrc format in the user's home directory. The format follows standard netrc conventions:

machine surge.surge.sh
  login user@example.com
  password api-token-here

Error Handling

Common Authentication Errors

• Unauthenticated: No valid credentials found
• Forbidden: Invalid credentials or expired token
• Client Upgrade Required: CLI version needs updating

All authentication commands handle these errors gracefully with informative error messages.