Deployments

Deploy your sites and manage deployment history.

init

Create a zerodeploy.json config file to avoid repetitive CLI flags.

zerodeploy init [options]

Option	Description
`--site <site>`	Site slug
`--dir <directory>`	Build output directory
`--build <command>`	Build command
`--ignore <patterns>`	Glob patterns to ignore during deploy
`--force`	Overwrite existing config file

bash

# Create config file (auto-detects framework)
zerodeploy init --site my-website

This creates zerodeploy.json:

json

{
  "site": "my-website",
  "dir": "dist",
  "build": "npm run build",
  "ignore": ["*.map", "drafts/"]
}

Now deploy with a single command:

bash

zerodeploy deploy           # deploy only
zerodeploy deploy --build   # build + deploy

Config Options

Field	Description
`site`	Site slug
`dir`	Build output directory
`build`	Build command (used with `--build` flag)
`install`	Install command (used with `--install` flag)
`ignore`	Glob patterns to exclude from deploy (e.g., `["*.map", "drafts/"]`)

CLI flags always take precedence over config values.

deploy

Deploy a directory to a site.

zerodeploy deploy [site] [options]

Option	Description
`--org <org>`	Organization for auto-creating new sites
`--dir <directory>`	Directory to deploy (from config, or auto-detected)
`--build`	Run build command before deploying
`--no-build`	Skip build step
`--build-command <cmd>`	Override the build command
`--install`	Run install command before building
`--append`	Keep existing files and add new ones on top
`--preview`	Deploy without setting as current (preview only)
`--no-verify`	Skip deployment verification
`--no-auto-rollback`	Disable automatic rollback on verification failure

bash

# Deploy (org/site from zerodeploy.json)
zerodeploy deploy

# Deploy specific directory
zerodeploy deploy --dir ./dist

# Build and deploy
zerodeploy deploy --build

# Install, build, and deploy
zerodeploy deploy --install --build

# Append files to existing deployment (keeps old files)
zerodeploy deploy --append

# Deploy a specific site
zerodeploy deploy my-website --dir ./dist

Deploy Verification

After each deployment, the CLI automatically verifies your site is live by hitting the URL and checking for a 200 response. This catches DNS issues, misconfigurations, and broken deploys before you walk away.

text

Finalizing...
Verifying...

Deployment successful!
URL:     https://my-site.zerodeploy.app (verified)
Preview: https://abc12345-my-site.zerodeploy.app

Use --no-verify to skip verification if needed.

Auto-Rollback on Failure

If verification fails (site returns an error or times out), the CLI automatically rolls back to the previous working deployment. This ensures your site is never left broken.

text

Verifying...

Warning: Could not verify deployment
  Received status 502

Auto-rolling back to previous deployment...
Rolled back to a1b2c3d4

Deployment failed verification and was rolled back.
Failed deployment: e5f6g7h8
Check manually: https://my-site.zerodeploy.app

Use --no-auto-rollback to disable automatic rollback. Auto-rollback is skipped for preview deployments since they don't affect your live site.

Framework Auto-Detection

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

Framework	Detection	Output Dir
Vite	`vite` in deps	`dist/`
Next.js	`next` in deps	`out/`
Create React App	`react-scripts` in deps	`build/`
Vue CLI	`@vue/cli-service` in deps	`dist/`
Astro	`astro` in deps	`dist/`
SvelteKit	`@sveltejs/kit` in deps	`build/`
Gatsby	`gatsby` in deps	`public/`

Preview URLs

Every deployment gets two URLs:

Production URL: https://subdomain.zerodeploy.app - Always serves the current deployment
Preview URL: https://{shortId}-subdomain.zerodeploy.app - Serves this specific deployment

Preview Deployments

Deploy without going live immediately. Useful for client review or staging before promoting to production.

Deploy as Preview

Use the --preview flag to deploy without setting as the current (live) deployment:

bash

zerodeploy deploy --preview

Output:

text

Preview deployment created!
Preview: https://abc12345-mysite.zerodeploy.app

To make this deployment live, run:
  zerodeploy deploy promote abc12345

Promote to Production

After reviewing the preview, promote it to production:

zerodeploy deploy promote <deploymentId>

bash

# Promote using short ID (first 8 chars)
zerodeploy deploy promote abc12345

# Or use full deployment ID
zerodeploy deploy promote 019b1234-5678-90ab-cdef-1234567890ab

The deployment instantly becomes the live version at your production URL.

Preview Workflow Example

bash

# 1. Deploy as preview
zerodeploy deploy --preview
# → Preview: https://abc12345-mysite.zerodeploy.app

# 2. Share preview URL with client for review
# 3. Client approves...

# 4. Promote to production
zerodeploy deploy promote abc12345
# → Now live at https://mysite.zerodeploy.app

deploy promote

Promote a preview deployment to production. When no ID is given, promotes the latest preview deployment.

zerodeploy deploy promote [deploymentId] [options]

Argument	Description
`deploymentId`	Deployment ID (defaults to latest preview deployment)

Option	Description
`--site <site>`	Site slug (defaults to config/env)
`--json`	Output as JSON for scripting

bash

# Promote the latest preview (uses config for site)
zerodeploy deploy promote

# Promote a specific deployment
zerodeploy deploy promote abc12345

The deployment instantly becomes the live version at your production URL. See Preview Deployments for the full workflow.

GitHub Actions

Set up automated deployments with GitHub Actions.

CI/CD Options

Git metadata is automatically detected in CI environments. The CLI recognizes GitHub Actions, CircleCI, GitLab CI, Bitbucket Pipelines, Azure Pipelines, Travis CI, and Jenkins. You can override auto-detected values using these flags:

Option	Description
`--pr <number>`	PR number (auto-detected in CI)
`--pr-title <title>`	PR title (auto-detected in some CI)
`--commit <sha>`	Commit SHA (auto-detected in CI)
`--commit-message <msg>`	Commit message (auto-detected in some CI)
`--branch <branch>`	Branch name (auto-detected in CI)
`--github-output`	Output deployment info in GitHub Actions format

Minimal Workflow

yaml

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: Deploy
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
        run: npx @zerodeploy/cli deploy --dir dist

PR Preview Workflow

Git metadata (PR number, commit SHA, branch) is auto-detected from the GitHub Actions environment:

yaml

- name: Deploy PR Preview
  if: github.event_name == 'pull_request'
  env:
    ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
  run: npx @zerodeploy/cli deploy --dir dist

You can override auto-detected values if needed:

yaml

- name: Deploy PR Preview
  env:
    ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
  run: |
    npx @zerodeploy/cli deploy --dir dist \
      --pr ${{ github.event.pull_request.number }} \
      --commit ${{ github.sha }} \
      --branch ${{ github.head_ref }}

deployments list

List deployment history for a site.

zerodeploy deployments list [site] [options]

Option	Description
`--json`	Output as JSON for scripting

bash

zerodeploy deployments list

Example output:

text

Deployments:

  019b1234  ready       12/14/2025, 9:00:00 PM (current)
            [abc1234] (main) - Fix header styling

  019b1230  ready       12/14/2025, 8:30:00 PM
            [def5678] (main) - Add new feature

  019b1220  ready       12/14/2025, 8:00:00 PM

deployments show

View detailed information about a deployment. When no ID is given, shows the current production deployment.

zerodeploy deployments show [id] [options]

Argument	Description
`id`	Deployment ID (defaults to current deployment)

Option	Description
`--site <site>`	Site slug (defaults to config/env)
`--json`	Output as JSON for scripting

bash

zerodeploy deployments show 019b1234

Example output:

text

Deployment Details
==================================================

ID:        019b1234-5678-9abc-def0-1234567890ab
Status:    ✅ Ready
Created:   12/14/2025, 9:00:00 PM

URLs
--------------------------------------------------
Production:  https://my-site.zerodeploy.app
Preview:     https://019b1234-my-site.zerodeploy.app

Git Info
--------------------------------------------------
Branch:    main
Commit:    abc1234567890
Message:   Fix header styling

Files
--------------------------------------------------
Count:     156 files
Size:      2.4 MB

deployments logs

View structured logs from the deployment finalize process. Useful for debugging failed or slow deployments. When no ID is given, shows logs for the latest deployment.

zerodeploy deployments logs [id] [options]

Argument	Description
`id`	Deployment ID (defaults to latest deployment)

Option	Description
`--site <site>`	Site slug (defaults to config/env)
`--json`	Output as JSON for scripting

bash

zerodeploy deployments logs 019b1234

Logs include timing, phase, and metadata for each step of the finalize process (extraction, validation, upload, cache invalidation).

rollback

Roll back to a previous deployment.

zerodeploy rollback [site] [options]

Option	Description
`--to <deploymentId>`	Deployment ID to rollback to (defaults to previous deployment)

bash

# Rollback to previous deployment (site from config/env)
zerodeploy rollback

# Rollback to specific deployment
zerodeploy rollback --to 019b1230

The specified deployment becomes the current live deployment instantly. You can use the full deployment ID or just the first 8 characters.

SPA Support

ZeroDeploy automatically handles SPA (Single Page Application) routing:

Requests without file extensions fall back to index.html
Enables client-side routing for React, Vue, Angular, etc.
Custom 404.html is served for missing pages

Caching

Cache headers are set automatically based on file type:

File Type	Cache Strategy
HTML files	`max-age=0, must-revalidate`
Hashed assets (e.g., `main.abc123.js`)	`max-age=31536000, immutable`
Other assets	`max-age=3600, stale-while-revalidate`

Previous Sites Next Custom Domains