Features

• ⚡ Lightning Fast: Deploy in seconds with real-time progress
• 🔒 Password Protection: Built-in HTTP Basic Auth support
• 🚀 SPA Routing: Automatic fallback to index.html for single-page apps
• 📊 Quota Management: Track storage usage and project limits
• 🎯 Custom Domains: Support for CNAME records and custom subdomains
• 📱 Mobile Friendly: Responsive deployment interface
• 🔄 Auto-retry: Intelligent retry logic for reliable uploads
• 🌐 Multi-gateway: Fallback gateway support for high availability

Deploy Now

Just Run:

npx htmsh ./dist my-awesome-site

Your site will be live at https://my-awesome-site.htm.sh

Installation

NPX (Recommended)

npx htmsh [options] [path] [domain]

Global Installation

npm install -g htmsh
htmsh [options] [path] [domain]

Usage

Basic Deployment

# Deploy current directory
htmsh

# Deploy specific directory
htmsh ./build

# Deploy with custom subdomain
htmsh ./dist my-project

# Deploy with options
htmsh ./public my-site --no-spa --password secret123

Authentication

Before deploying, authenticate once:

htmsh login

Your credentials are cached locally with configurable TTL:

htmsh login --ttl 7d  # Cache for 7 days
htmsh whoami          # Check current status
htmsh logout          # Clear credentials

Password Protection

Protect your site with HTTP Basic Auth:

# Set password via command line
htmsh ./dist --password mypassword

# Create AUTH file in your project
echo "username:password" > AUTH
htmsh ./dist

# Remove password protection
htmsh ./dist --remove-password

SPA (Single Page Application) Support

By default, htm.sh enables SPA routing (unknown paths redirect to index.html):

# Deploy with SPA routing (default)
htmsh ./build

# Disable SPA routing for multi-page apps
htmsh ./build --no-spa

Custom Domains

Using CNAME File

Create a CNAME file in your project root:

echo "my-custom-subdomain" > CNAME
htmsh ./dist

Command Line

htmsh ./dist my-custom-subdomain

Project Management

# Check quota and project usage
htmsh quota

# View help and tips
htmsh tips
htmsh docs

# Show comprehensive documentation
htmsh docs --section password  # Show specific section

Project Structure

your-project/
├── index.html          # Required: at least one .html file
├── CNAME              # Optional: custom subdomain
├── AUTH               # Optional: username:password for protection
├── assets/
└── ...

Commands

Main Command

htmsh [path] [domain] [options]

Arguments:

• path: Directory to publish (default: current directory)
• domain: Desired subdomain (extracted from CNAME if not provided)

Options:

• --no-spa: Disable SPA routing fallback
• --password <pwd>: Password protect the site
• --remove-password: Remove existing password protection
• --yes: Skip confirmation prompts
• --quiet: Suppress standard output
• --json: Machine-readable output for CI/CD

Utility Commands

| Command | Description | |---------|-------------| | login | Authenticate and cache credentials | | logout | Clear cached credentials | | whoami | Show current user and gateway status | | quota | Display storage usage and project limits | | tips | Show quick usage tips | | docs | Comprehensive documentation |

Examples

Basic Static Site

# Build your site
npm run build

# Deploy to htm.sh
htmsh ./build my-portfolio

React/Vue SPA

# Build production bundle
npm run build

# Deploy with SPA routing (default)
htmsh ./dist react-app

# Your app is live at https://react-app.htm.sh

Password Protected Site

# Method 1: Command line
htmsh ./dist private-docs --password secret123

# Method 2: AUTH file
echo "admin:supersecret" > ./dist/AUTH
htmsh ./dist private-docs

CI/CD Integration

# Non-interactive deployment
htmsh ./build my-app --yes --json --quiet

# With environment credentials
export DEPLOY_GATEWAY="https://htm.sh"
htmsh ./dist staging-app --yes

Multi-environment Setup

# Production
htmsh ./build my-app

# Staging
htmsh ./build my-app-staging

# Development
htmsh ./build my-app-dev --password devpass

JSON Output

For CI/CD and scripting, use --json flag:

{
  "event": "deployed",
  "url": "https://my-project.htm.sh",
  "project": "my-project",
  "subdomain": "my-project.htm.sh",
  "release": "abc123",
  "files": 42,
  "sizeBytes": 1048576,
  "passwordProtected": false,
  "gateway": "https://htm.sh"
}

Quota Management

Monitor your usage:

$ htmsh quota

quota
─────────────────────────────────────────────────────────────────────
  Limit:             100 MB
  Used:              45.2 MB
  Remaining:         54.8 MB

projects
─────────────────────────────────────────────────────────────────────
  my-portfolio       15.3 MB • 3 release(s) • last: 2024-01-15
  landing-page       12.1 MB • 1 release(s) • last: 2024-01-10
  docs-site          17.8 MB • 5 release(s) • last: 2024-01-14

Troubleshooting

Common Issues

Directory not found

# Check your path
htmsh ./correct-build-path

No .html file found

# Ensure at least one HTML file exists in project root
ls *.html

401 Unauthorized

# Login first
htmsh login

Subdomain conflict

# Choose a different name
htmsh ./dist my-unique-project-name

Railway Gateway Issues The CLI automatically detects Railway hosts and suggests switching to the public gateway for better reliability.

Debug Mode

# Enable verbose output
htmsh ./dist --json | jq '.'

# Check gateway health
htmsh whoami

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation: htmsh docs
• 💡 Tips: htmsh tips
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Built with ❤️ for developers who want to ship fast.