# ZeroDeploy

> 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.

## For AI Agents

If a user asks you to deploy a static site or SPA:

### Drop (No Login Required)

Deploy instantly with one HTTP call. No authentication needed.

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

#### Multi-file (tar.gz)
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

Returns: { url, claim_token, expires_at }
Sites expire in 72 hours unless claimed. Redeploy with X-Claim-Token header to update and reset the timer.

#### Redeploy (update existing site)
curl -X POST https://api.zerodeploy.dev/drop \
  -H "Content-Type: text/html" \
  -H "X-Claim-Token: zdr_..." \
  --data-binary @index.html

#### 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 file: curl -X POST https://api.zerodeploy.dev/drop -H "Content-Type: text/html" --data-binary @index.html

### CLI Deploy (Full Features)

For ongoing projects with CI/CD, custom domains, and deployment history:

1. Install: `npm install -g @zerodeploy/cli`
2. Login: `zerodeploy login` (opens browser for GitHub OAuth)
3. Deploy: `zerodeploy deploy --json`

The CLI auto-creates org and site on first deploy. No prior setup needed.

### When to use Drop vs CLI
- **Drop:** Quick one-off deploys, prototypes, demos. Zero setup. Sites expire in 72h unless claimed.
- **CLI:** Ongoing projects, CI/CD, custom domains, rollbacks, analytics, forms. Requires login.

### Machine-readable output
All CLI commands support `--json`. Exit codes: 0=success, 1=auth, 2=not found, 3=validation, 4=rate limit, 5=server, 6=network, 7=billing.

## Documentation

- [Quick Start](https://zerodeploy.dev/docs/quickstart): Get started in minutes
- [CLI Reference](https://zerodeploy.dev/docs/cli): Complete CLI command documentation
- [API Reference](https://zerodeploy.dev/docs/api): REST API documentation
- [Frameworks Guide](https://zerodeploy.dev/docs/frameworks): Static export instructions for popular frameworks
- [GitHub Integration](https://zerodeploy.dev/docs/github): PR preview comments and CI/CD setup
- [Full Documentation](https://zerodeploy.dev/llms-full.txt): Complete docs in single file (for LLMs)

## Machine-Readable

- [OpenAPI Spec](https://api.zerodeploy.dev/openapi.json): OpenAPI 3.1 specification

## Quick Start

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

# Login with GitHub
zerodeploy login

# Deploy your site
zerodeploy deploy ./dist
```

## Core Commands

### Authentication
- `zerodeploy login` - Login via GitHub OAuth
- `zerodeploy logout` - Clear stored credentials
- `zerodeploy whoami` - Show current user

### Organizations
- `zerodeploy org list` - List your organizations
- `zerodeploy org create <slug>` - Create organization
- `zerodeploy org delete <org>` - Delete organization

### Sites
- `zerodeploy site list` - List all your sites
- `zerodeploy site create <slug> [--org <org>]` - Create site
- `zerodeploy site delete [site]` - Delete site
- `zerodeploy site stats [site]` - View traffic analytics

### Deployments
- `zerodeploy deploy` - Deploy using zerodeploy.json config
- `zerodeploy deploy [site] [--dir <path>]` - Deploy with options
- `zerodeploy deploy --append` - Add files to existing deployment instead of replacing
- `zerodeploy deployments list [site]` - List deployments
- `zerodeploy rollback [site]` - Rollback to previous

### Custom Domains
- `zerodeploy domain add <domain> [--site <site>]` - Add domain
- `zerodeploy domain verify <domain> [--site <site>]` - Verify DNS
- `zerodeploy domain list [--site <site>]` - List domains

### API Tokens
- `zerodeploy token create <name>` - Create Personal Access Token (PAT)
- `zerodeploy token create <name> --site <siteId>` - Create site deploy token for CI/CD
- `zerodeploy token create <name> --org <slug>` - Create org deploy token for monorepo CI/CD
- `zerodeploy token list` - List all tokens
- `zerodeploy token list --type user` - List PATs only
- `zerodeploy token list --type site` - List site deploy tokens only
- `zerodeploy token list --type org` - List org deploy tokens only
- `zerodeploy token delete <tokenId>` - Delete token

### Billing
- `zerodeploy billing` - Show account balance and usage (alias for billing usage)
- `zerodeploy billing usage` - Show balance, can_deploy status, estimated costs
- `zerodeploy billing bills` - Show monthly billing history
- `zerodeploy billing adjustments` - Show balance adjustment history (credits)

### Forms
- `zerodeploy form list [--site <site>]` - List forms
- `zerodeploy form submissions <name> [--site <site>]` - View submissions
- `zerodeploy form export <name> [--site <site>]` - Export as CSV
- `zerodeploy form delete <name> [--site <site>]` - Delete form and submissions
- `zerodeploy form notify <name> [--site <site>] --email <email>` - Enable notifications
- `zerodeploy form notify <name> [--site <site>] --disable` - Disable notifications

### Account
- `zerodeploy usage` - Show current usage and plan limits
- `zerodeploy account delete` - Permanently delete account (GDPR)
- `zerodeploy inspect` - Output CLI metadata as JSON (for LLM/automation)

## 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.

## Features

- **Instant Deployments**: Deploy static sites in seconds
- **Custom Domains**: Add your own domains with automatic SSL
- **Form Handling**: Built-in form submissions with notifications
- **Analytics**: Traffic analytics for your sites
- **Rollbacks**: One-click rollback to any previous deployment
- **CI/CD**: Deploy tokens for automated pipelines
- **GitHub App**: Connect repos for PR preview comments with live status updates
- **Monorepo Support**: Path filters and org-scoped tokens for multi-site repos