ZeroDeploy CLI

Command-line interface for deploying static sites and SPAs to ZeroDeploy.

Installation

npm install -g @zerodeploy/cli

Or use directly with npx:

npx @zerodeploy/cli deploy

Quick Start

# 1. Login with GitHub
zerodeploy login

# 2. Create an organization
zerodeploy org create "My Company"

# 3. Create a site
zerodeploy site create my-company "My Website" --subdomain my-website

# 4. Deploy your site
zerodeploy deploy my-website --org my-company --dir ./dist

Your site will be live at https://my-website.zerodeploy.app

Commands

Authentication

zerodeploy login

Authenticate with GitHub OAuth. Opens your browser for authentication.

zerodeploy login

zerodeploy logout

Clear stored authentication token.

zerodeploy logout

zerodeploy whoami

Display current logged-in user information.

zerodeploy whoami

Organizations

zerodeploy org list

List all organizations you have access to.

zerodeploy org list

zerodeploy org create <name>

Create a new organization.

zerodeploy org create "My Company"

zerodeploy org delete <orgSlug>

Delete an organization (must have no sites).

zerodeploy org delete my-company

Sites

zerodeploy site list <orgSlug>

List all sites in an organization.

zerodeploy site list my-company

zerodeploy site create <orgSlug> <name> --subdomain <subdomain>

Create a new site in an organization.

Options:

• --subdomain <subdomain> - Subdomain for the site (required, globally unique)
• --repo <owner/repo> - Link to a GitHub repository

# Create a site
zerodeploy site create my-company "My Website" --subdomain my-website

# Create a site linked to a GitHub repo
zerodeploy site create my-company "Dashboard" --subdomain dashboard --repo company/monorepo

Your site will be available at https://<subdomain>.zerodeploy.app

zerodeploy site delete <siteSlug> --org <orgSlug>

Delete a site and all its deployments.

zerodeploy site delete my-website --org my-company

Deployment

zerodeploy deploy <siteSlug> [options]

Deploy a directory to a site.

Options:

• --org <orgSlug> - Organization slug (required)
• --dir <directory> - Directory to deploy (default: auto-detect)
• --build - Run build command before deploying
• --build-command <cmd> - Custom build command
• --install - Run install command before building

# Deploy specific directory
zerodeploy deploy my-website --org my-company --dir ./dist

# Auto-detect build directory
zerodeploy deploy my-website --org my-company

# Build and deploy
zerodeploy deploy my-website --org my-company --build

# Install dependencies, build, and deploy
zerodeploy deploy my-website --org my-company --install --build

Output:

Deploying: ./dist
Found 42 files (1.2 MB)
Uploading files...
  [100%] 42/42 files

Deployment successful!
URL:     https://my-website.zerodeploy.app
Preview: https://019b1234-my-website.zerodeploy.app

zerodeploy deployments list <siteSlug> --org <orgSlug>

List deployment history for a site.

zerodeploy deployments list my-website --org my-company

Options:

• --limit <number> - Number of deployments to show (default: 10)

zerodeploy rollback <siteSlug> --org <orgSlug>

Rollback to a previous deployment.

# Rollback to the previous deployment
zerodeploy rollback my-website --org my-company

# Rollback to a specific deployment
zerodeploy rollback my-website --org my-company --to 019b1230

Deploy Tokens

Deploy tokens allow CI/CD systems to authenticate without using your personal credentials.

zerodeploy token create <name> --org <org> --site <site>

Create a deploy token for CI/CD.

zerodeploy token create "GitHub Actions" --org my-company --site my-website

Save the token securely - it will only be shown once.

zerodeploy token list --org <org> --site <site>

List deploy tokens for a site.

zerodeploy token list --org my-company --site my-website

zerodeploy token delete <tokenId> --org <org> --site <site>

Delete a deploy token.

zerodeploy token delete 019b1234 --org my-company --site my-website

Custom Domains

Connect your own domain to any ZeroDeploy site with automatic SSL.

zerodeploy domain add <domain> --org <org> --site <site>

Add a custom domain to a site. Returns DNS verification instructions.

zerodeploy domain add www.example.com --org my-company --site my-website

zerodeploy domain verify <domain> --org <org> --site <site>

Verify domain ownership after adding the TXT record to your DNS.

zerodeploy domain verify www.example.com --org my-company --site my-website

zerodeploy domain list --org <org> --site <site>

List all custom domains for a site.

zerodeploy domain list --org my-company --site my-website

zerodeploy domain remove <domain> --org <org> --site <site>

Remove a custom domain from a site.

zerodeploy domain remove www.example.com --org my-company --site my-website

zerodeploy domain redirect <domain> --org <org> --site <site> --mode <mode>

Set redirect mode for a custom domain. This allows automatic redirects between www and apex (non-www) domains.

Options:

• --mode <mode> - Redirect mode: none, www_to_apex, or apex_to_www

# Redirect www.example.com to example.com
zerodeploy domain redirect example.com --org my-company --site my-website --mode www_to_apex

# Redirect example.com to www.example.com
zerodeploy domain redirect www.example.com --org my-company --site my-website --mode apex_to_www

# Disable redirects
zerodeploy domain redirect example.com --org my-company --site my-website --mode none

Custom Domain Setup:

1. Add the domain: zerodeploy domain add www.example.com --org my-org --site my-site
2. Add the TXT record to your DNS (shown in output)
3. Verify ownership: zerodeploy domain verify www.example.com --org my-org --site my-site
4. Add the CNAME record to your DNS (shown in output)
5. Your site is now live at https://www.example.com

Configuration File

Create a zerodeploy.json in your project root:

zerodeploy init --org my-company --site my-website

This creates:

{
  "org": "my-company",
  "site": "my-website"
}

Then deploy with just:

zerodeploy deploy

Deployed Sites

URLs

Each site gets a production URL based on its subdomain:

https://<subdomain>.zerodeploy.app

Preview URLs

Every deployment also gets a unique preview URL that remains accessible even after new deployments:

https://<deploymentId>-<subdomain>.zerodeploy.app

Preview URLs use the first 8 characters of the deployment ID. Useful for:

• Reviewing changes before promoting to production
• Sharing specific versions with stakeholders
• Comparing different deployments

SPA Support

ZeroDeploy automatically handles SPA (Single Page Application) routing:

• Requests without file extensions fall back to index.html
• Works with React Router, Vue Router, and other client-side routers

Caching

Cache headers are set automatically:

• HTML files: Always revalidate for fresh content
• Hashed assets (e.g., main.abc123.js): Cached for 1 year
• Other assets: Cached for 1 hour with background revalidation

CI/CD Integration

GitHub Actions

1. Create a deploy token:

zerodeploy token create "GitHub Actions" --org my-company --site my-website

2. Add the token to your repository secrets as ZERODEPLOY_TOKEN

3. Create .github/workflows/deploy.yml:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Deploy
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
        run: npx @zerodeploy/cli deploy my-site --org my-org

PR Preview workflow:

name: PR Preview
on:
  pull_request:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Deploy Preview
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
        run: |
          npx @zerodeploy/cli deploy my-site \
            --org my-org \
            --pr ${{ github.event.pull_request.number }} \
            --pr-title "${{ github.event.pull_request.title }}" \
            --commit ${{ github.sha }} \
            --branch ${{ github.head_ref }} \
            --github-output

The --github-output flag exports deployment info as GitHub Actions outputs:

• deployment_id - The deployment ID
• deployment_url - The production URL
• preview_url - The unique preview URL

Other CI/CD Systems

ZeroDeploy works with any CI/CD system. Set the ZERODEPLOY_TOKEN environment variable and run the deploy command:

# Works with npm, yarn, pnpm, or bun
npx @zerodeploy/cli deploy my-site --org my-org
yarn dlx @zerodeploy/cli deploy my-site --org my-org
pnpm dlx @zerodeploy/cli deploy my-site --org my-org
bunx @zerodeploy/cli deploy my-site --org my-org

Framework Auto-Detection

The CLI automatically detects your framework and uses the appropriate build command and output directory:

| Framework | Build Command | Output Dir | |-----------|---------------|------------| | Vite | npm run build | dist/ | | Next.js | npm run build | out/ | | Create React App | npm run build | build/ | | Vue CLI | npm run build | dist/ | | Nuxt | npm run build | dist/ | | Astro | npm run build | dist/ | | SvelteKit | npm run build | build/ | | Gatsby | npm run build | public/ | | Remix | npm run build | public/build/ | | Parcel | npm run build | dist/ |

Auto-detected directories (fallback): If no framework is detected, the CLI looks for: dist/, build/, out/, public/

Ignored files: The following are automatically excluded from deployments:

• node_modules/
• .git/
• .env, .env.* files
• Hidden files starting with .

Environment Variables

| Variable | Description | |----------|-------------| | ZERODEPLOY_TOKEN | Authentication token (for CI/CD) | | ZERODEPLOY_API_URL | Custom API URL (defaults to production) |

Troubleshooting

"Not logged in"

Run zerodeploy login to authenticate.

"Org not found"

Use the correct org slug (lowercase, hyphenated). Check with zerodeploy org list.

"Site not found"

Use the correct site and org slugs. Check with zerodeploy site list <orgSlug>.

"No build directory found"

Either:

• Specify the directory with --dir ./path/to/build
• Run with --build to build first
• Ensure your project has a dist/, build/, out/, or public/ directory

Links

• Documentation
• Support