# ZeroDeploy - Complete Documentation

> Static site hosting with forms, analytics, and email notifications built in.

ZeroDeploy is a static site hosting platform that deploys sites and SPAs in under 5 seconds via CLI or drag-and-drop dashboard. It includes forms, privacy-friendly analytics, custom domains, preview URLs, and email notifications out of the box — replacing the stack of separate services developers typically need.

This file contains complete documentation for ZeroDeploy, optimized for LLM consumption.

---

## Quick Start

```bash
# Install CLI
npm install -g @zerodeploy/cli

# Login with GitHub
zerodeploy login

# Deploy your site
cd my-project
zerodeploy deploy
```

---

## Configuration

Create `zerodeploy.json` in your project root:

```json
{
  "org": "your-org",
  "site": "your-site",
  "dir": "dist",
  "build": "npm run build"
}
```

Or use environment variables: `ZERODEPLOY_ORG` and `ZERODEPLOY_SITE`.

Context resolution order: CLI flags > environment variables > zerodeploy.json. Most site-scoped commands (deploy, domains, forms, etc.) resolve org/site automatically from config or env vars, so flags are optional.

---
## Drop API (Zero Auth)

Deploy with one HTTP call. No login, no CLI, no setup. Sites expire in 72 hours unless claimed.

### Single file (simplest)
```bash
curl -X POST https://api.zerodeploy.dev/drop \
  -H "Content-Type: text/html" \
  --data-binary @index.html
```

### Multi-file (tar.gz)
```bash
tar -czf site.tar.gz -C ./dist .
curl -X POST https://api.zerodeploy.dev/drop \
  -H "Content-Type: application/gzip" \
  --data-binary @site.tar.gz
```

### Response
Returns JSON: { data: { url, claim_token, expires_at }, next_steps: { redeploy, claim } }

### Redeploy (update existing site)
Pass the claim token via X-Claim-Token header to update the same site and reset the 72-hour timer:
```bash
curl -X POST https://api.zerodeploy.dev/drop \
  -H "Content-Type: text/html" \
  -H "X-Claim-Token: zdr_..." \
  --data-binary @index.html
```

### Limits
- 10 MB max per file, 1,000 files max, 25 MB total per deployment
- 5 deploys per hour per IP address
- 72 hours expiration (reset on each redeploy)

### Framework examples
- React/Vite/Astro: cd dist && tar -czf ../site.tar.gz . && curl -X POST https://api.zerodeploy.dev/drop -H "Content-Type: application/gzip" --data-binary @../site.tar.gz
- Next.js (static): cd out && tar -czf ../site.tar.gz . && curl -X POST https://api.zerodeploy.dev/drop -H "Content-Type: application/gzip" --data-binary @../site.tar.gz
- Single HTML: curl -X POST https://api.zerodeploy.dev/drop -H "Content-Type: text/html" --data-binary @index.html

### When to use Drop vs CLI
- Drop: Quick one-off deploys, prototypes, demos. Zero setup. Best for "deploy this now."
- CLI: Ongoing projects, CI/CD, custom domains, rollbacks, analytics, forms. Best for "set up a site I'll maintain."

---
## CLI Commands Reference

All commands support `--help` for detailed usage information.
Most data-returning commands support `--json` for machine-readable output.

### Authentication

- `zerodeploy login` - Authenticate with GitHub OAuth
- `zerodeploy logout` - Clear stored authentication token
- `zerodeploy whoami [--json]` - Display current logged-in user
- `zerodeploy usage [--json]` - Show current usage and plan limits
- `zerodeploy account email <email>` - Set notification email
- `zerodeploy account delete [--force]` - Permanently delete account (GDPR)

### Organizations

- `zerodeploy org list [--json]` - List organizations
- `zerodeploy org create <slug> [--json]` - Create organization
- `zerodeploy org delete [slug] [--org <org>] [--force]` - Delete organization (must have no sites)

### Sites

- `zerodeploy site list [--json]` - List all sites
- `zerodeploy site create <slug> [--org <org>] [--repo <owner/repo>] [--json]` - Create site
- `zerodeploy site stats [site] [--period 24h|7d|30d] [--json]` - View traffic analytics
- `zerodeploy site link <repo> [--site <site>]` - Link site to GitHub repo
- `zerodeploy site unlink [--site <site>]` - Unlink site from GitHub repo
- `zerodeploy site delete [slug] [--force]` - Delete site and all deployments

### Deployments

- `zerodeploy init --site <site> [--ignore "*.map" "drafts/"]` - Create zerodeploy.json config
- `zerodeploy deploy [site] [--org <org>] [--dir <path>] [--build] [--append] [--preview]` - Deploy directory to site
- `zerodeploy deploy promote [deploymentId] [--site <site>] [--json]` - Promote preview deployment to production
- `zerodeploy deployments list [site] [--json]` - List deployment history
- `zerodeploy deployments show [id] [--site <site>] [--json]` - View deployment details
- `zerodeploy deployments logs [id] [--site <site>] [--json]` - View deployment finalize logs
- `zerodeploy rollback [site] [--to <id>]` - Rollback to previous deployment

### Domains

- `zerodeploy domain add <domain> [--site <site>]` - Add custom domain
- `zerodeploy domain verify <domain> [--site <site>]` - Verify domain ownership
- `zerodeploy domain list [--site <site>] [--json]` - List custom domains
- `zerodeploy domain remove <domain> [--site <site>]` - Remove custom domain
- `zerodeploy domain redirect <domain> [--site <site>] --mode <none|www_to_apex|apex_to_www>` - Set redirect mode

### Tokens

- `zerodeploy token create <name> [--site <slugOrId>] [--org <slug>] [--expires <days>] [--json]` - Create API token
- `zerodeploy token list [--type user|site|org] [--json]` - List tokens
- `zerodeploy token delete <tokenId>` - Delete token

### Forms

- `zerodeploy form list [--site <site>] [--json]` - List forms
- `zerodeploy form submissions <name> [--site <site>] [--limit <n>] [--json]` - View submissions
- `zerodeploy form export <name> [--site <site>] [-o <file>]` - Export submissions as CSV
- `zerodeploy form delete <name> [--site <site>] [--force]` - Delete form
- `zerodeploy form notify <name> [--site <site>] --email <email> | --disable` - Configure email notifications

### Billing

- `zerodeploy billing [--json]` - Show subscription status and billing info
- `zerodeploy billing usage [--org <slug>] [--json]` - Show current usage and estimated costs

### Utility

- `zerodeploy update` - Update CLI to latest version
- `zerodeploy inspect [command...]` - Output command metadata as JSON

---
## REST API Reference

Base URL: `https://api.zerodeploy.dev`

### Authentication

- **API Token**: Tokens with `zd_` prefix, sent as `Authorization: Bearer <token>`
- **Personal Access Token (PAT)**: User-scoped, full API access
- **Deploy Token**: Site or org-scoped, deploy operations only

### User

Get and manage current user information.

| Method | Path | Description | Auth |
|--------|------|-------------|------|

### Drop API

Deploy with one HTTP call. No login, no CLI, no setup. Sites expire in 72 hours unless claimed.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/drop` | Deploy a site instantly (no auth required) | Public |
| POST | `/drop/claim` | Claim an ephemeral site to make it permanent | Token |

### Organizations

Manage organizations (workspaces) that contain sites.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/orgs` | List organizations | Token |
| GET | `/orgs/:orgSlug` | Get organization | Token |

### Sites

Manage sites within organizations.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/sites` | List sites | Token |
| POST | `/sites` | Create site | Token |
| GET | `/sites/:slug` | Get site | Token |
| PATCH | `/sites/:slug` | Update site | Token |
| DELETE | `/sites/:slug` | Delete site | Token |
| PATCH | `/sites/:slug/password` | Update password protection | Token |

### Deployments

Deploy and manage site versions.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/deployments` | Create deployment | Token/Deploy |
| GET | `/sites/:slug/deployments` | List deployments | Token |
| GET | `/sites/:slug/deployments/by-commit` | Find deployment by commit SHA(s) | Token |
| GET | `/deployments/:id` | Get deployment | Token/Deploy |
| GET | `/deployments/:id/files` | List deployment files | Token |
| GET | `/deployments/:id/logs` | Get deployment logs | Token/Deploy |
| POST | `/deployments/:id/upload-and-finalize` | Upload and finalize deployment | Token |
| POST | `/deployments/:id/diff` | Diff deployment manifest | Token |
| POST | `/sites/:slug/diff` | Diff manifest against current deployment | Token |
| POST | `/deployments/:id/rollback` | Rollback to deployment | Token |

### Custom Domains

Add custom domains with automatic SSL to your sites.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/sites/:slug/domains` | Add custom domain | Token |
| GET | `/sites/:slug/domains` | List custom domains | Token |
| GET | `/sites/:slug/domains/:domainId` | Get domain | Token |
| DELETE | `/sites/:slug/domains/:domainId` | Remove custom domain | Token |
| POST | `/sites/:slug/domains/:domainId/verify` | Verify domain ownership | Token |
| PATCH | `/sites/:slug/domains/:domainId/redirect` | Update domain redirect mode | Token |

### API Tokens

Personal Access Tokens (PAT) and deploy tokens for API access.

| Method | Path | Description | Auth |
|--------|------|-------------|------|

### Forms

Manage form submissions from deployed sites.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/sites/:slug/forms` | List forms | Token |
| GET | `/sites/:slug/forms/:formName` | Get form | Token |
| PATCH | `/sites/:slug/forms/:formName` | Update form settings | Token |
| DELETE | `/sites/:slug/forms/:formName` | Delete form | Token |
| GET | `/sites/:slug/forms/:formName/submissions` | Get form submissions | Token |
| GET | `/sites/:slug/forms/:formName/export` | Export form submissions as CSV | Token |

### Analytics

Privacy-friendly site traffic analytics.

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/sites/:slug/analytics` | Get site analytics | Token |
| GET | `/sites/:slug/analytics/realtime` | Get real-time visitor count | Token |

---
## Features

- **Instant Deployments**: Deploy static sites in seconds via CLI or CI/CD
- **Preview URLs**: Every deployment gets a unique preview URL
- **Custom Domains**: Add your own domains with automatic SSL
- **Form Handling**: Built-in form submissions with email notifications
- **Analytics**: Privacy-friendly traffic analytics for your sites
- **Rollbacks**: One-click rollback to any previous deployment
- **Deploy Tokens**: Secure tokens for automated CI/CD pipelines
- **GitHub Integration**: Link sites to repos for branch-based previews

---

## Supported Frameworks

ZeroDeploy hosts static files only. Use static export mode for:

- **Vite** / **React** / **Vue** / **Svelte**: `npm run build` → `dist/`
- **Next.js**: `next build` (with `output: 'export'` in next.config.js) → `out/`
- **Nuxt**: `nuxt generate` → `.output/public/`
- **Astro**: `astro build` → `dist/`
- **Gatsby**: `gatsby build` → `public/`

---

## CI/CD Integration

### GitHub Actions Example

```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
        run: npx @zerodeploy/cli deploy
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}
          ZERODEPLOY_ORG: my-org
          ZERODEPLOY_SITE: my-site
```

The CLI resolves org/site from: flags > `ZERODEPLOY_ORG`/`ZERODEPLOY_SITE` env vars > `zerodeploy.json`. In CI/CD, env vars or a committed config file are the recommended approach.

### Creating Deploy Tokens

```bash
zerodeploy token create github-actions --site <site-id>
# Returns: zd_xxxxxxxxxxxx
# Add as ZERODEPLOY_TOKEN secret in GitHub
```

---

## Form Handling

Add forms to your static site without backend code:

```html
<form action="/_forms/contact" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>
```

Forms are automatically created on first submission. Manage via CLI:

```bash
zerodeploy form list
zerodeploy form submissions contact
zerodeploy form export contact > submissions.csv
```

When `zerodeploy.json` or `ZERODEPLOY_SITE` env var is set, the `--site` flag is optional.

---

## Links

- Website: https://zerodeploy.dev
- Documentation: https://zerodeploy.dev/docs
- CLI Reference: https://zerodeploy.dev/docs/cli
- API Reference: https://zerodeploy.dev/docs/api
- OpenAPI Spec: https://api.zerodeploy.dev/openapi.json
- Status: https://status.zerodeploy.dev