@zerodeploy/cli 0.1.13 → 0.1.15

package/README.md

@@ -34,402 +34,35 @@ Your site will be live at `https://my-website.zerodeploy.app`
 
 ## Commands
 
-### Authentication
-
-#### `zerodeploy login`
-
-Authenticate with GitHub OAuth. Opens your browser for authentication.
-
-```bash
-zerodeploy login
-```
-
-#### `zerodeploy logout`
-
-Clear stored authentication token.
-
-```bash
-zerodeploy logout
-```
-
-#### `zerodeploy whoami`
-
-Display current logged-in user information.
-
-```bash
-zerodeploy whoami
-```
-
-#### `zerodeploy usage`
-
-Display current usage and plan limits with visual progress bars.
-
-```bash
-zerodeploy usage
-```
-
-**Options:**
-- `--json` - Output as JSON for scripting
-
-### Organizations
-
-#### `zerodeploy org list`
-
-List all organizations you have access to.
-
-```bash
-zerodeploy org list
-```
-
-#### `zerodeploy org create <name>`
-
-Create a new organization.
-
-```bash
-zerodeploy org create "My Company"
-```
-
-#### `zerodeploy org delete <orgSlug>`
-
-Delete an organization (must have no sites).
-
-```bash
-zerodeploy org delete my-company
-```
-
-### Sites
-
-#### `zerodeploy site list <orgSlug>`
-
-List all sites in an organization.
-
-```bash
-zerodeploy site list my-company
-```
-
-#### `zerodeploy site create <orgSlug> <name>`
-
-Create a new site in an organization. The subdomain is auto-generated from the name.
-
-**Options:**
-- `--repo <owner/repo>` - Link to a GitHub repository
-
-```bash
-# Create a site
-zerodeploy site create my-company "My Website"
-
-# Create a site linked to a GitHub repo
-zerodeploy site create my-company "Dashboard" --repo company/monorepo
-```
-
-Your site will be available at `https://<subdomain>.zerodeploy.app`
-
-#### `zerodeploy site rename <siteSlug> <newName> --org <orgSlug>`
-
-Rename a site's display name.
-
-```bash
-zerodeploy site rename my-website "New Website Name" --org my-company
-```
-
-Note: This changes the display name, not the slug or subdomain.
-
-#### `zerodeploy site link <orgSlug> <siteSlug> <repo>`
-
-Link a site to a GitHub repository.
-
-```bash
-zerodeploy site link my-company dashboard company/monorepo
-```
-
-#### `zerodeploy site unlink <orgSlug> <siteSlug>`
-
-Remove the GitHub repository link from a site.
-
-```bash
-zerodeploy site unlink my-company dashboard
-```
-
-#### `zerodeploy site subdomain <orgSlug> <siteSlug> <subdomain>`
-
-Update the subdomain for a site.
-
-```bash
-zerodeploy site subdomain my-company my-website new-subdomain
-```
-
-After updating, your site will be accessible at `https://new-subdomain.zerodeploy.app`.
-
-#### `zerodeploy site delete <siteSlug> --org <orgSlug>`
-
-Delete a site and all its deployments.
-
-**Options:**
-- `--force` - Skip confirmation prompt
-
-```bash
-zerodeploy site delete my-website --org my-company
-```
-
-### Deployment
-
-#### `zerodeploy deploy [siteSlug] [options]`
-
-Deploy a directory to a site. If using a `zerodeploy.json` config file, site and org can be omitted.
-
-**Options:**
-- `--org <orgSlug>` - Organization slug (required, or from config)
-- `--dir <directory>` - Directory to deploy (default: auto-detect)
-- `--build` - Run build command before deploying
-- `--no-build` - Skip build step
-- `--build-command <cmd>` - Custom build command
-- `--install` - Run install command before building
-- `--preview` - Deploy without setting as current (preview only)
-- `--no-verify` - Skip deployment verification
-- `--no-auto-rollback` - Disable automatic rollback on verification failure
-
-**CI/CD Options:**
-- `--pr <number>` - PR number
-- `--pr-title <title>` - PR title
-- `--commit <sha>` - Commit SHA
-- `--branch <branch>` - Branch name
-- `--github-output` - Output deployment info in GitHub Actions format
-
-```bash
-# 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
-
-# Deploy as preview (doesn't go live)
-zerodeploy deploy my-website --org my-company --preview
-```
-
-Output:
-```
-Deploying: ./dist
-Found 42 files (1.2 MB)
-Uploading...
-Finalizing...
-Verifying...
-
-Deployment successful!
-URL:     https://my-website.zerodeploy.app (verified)
-Preview: https://abc12345-my-website.zerodeploy.app
-```
-
-#### `zerodeploy deploy promote <deploymentId>`
-
-Promote a preview deployment to production.
-
-```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
-```
-
-#### `zerodeploy deployments list <siteSlug> --org <orgSlug>`
-
-List deployment history for a site.
-
-```bash
-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.
-
-```bash
-# 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.
-
-```bash
-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.
-
-```bash
-zerodeploy token list --org my-company --site my-website
-```
-
-#### `zerodeploy token delete <tokenId> --org <org> --site <site>`
-
-Delete a deploy token.
-
-```bash
-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.
-
-```bash
-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.
-
-```bash
-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.
-
-```bash
-zerodeploy domain list --org my-company --site my-website
-```
-
-#### `zerodeploy domain remove <domain> --org <org> --site <site>`
-
-Remove a custom domain from a site.
-
-```bash
-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`
-
-```bash
-# 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`
-
-### Forms
-
-Collect form submissions from your static sites without a backend. Get email notifications when forms are submitted.
-
-#### `zerodeploy form list --org <org> --site <site>`
-
-List all forms for a site with submission counts.
-
-```bash
-zerodeploy form list --org my-company --site my-website
-```
-
-#### `zerodeploy form export <name> --org <org> --site <site>`
-
-Export form submissions as CSV.
-
-**Options:**
-- `-o, --output <file>` - Output file path (default: `<name>-submissions.csv`)
-
-```bash
-# Export to default file
-zerodeploy form export contact --org my-company --site my-website
-
-# Export to custom file
-zerodeploy form export contact --org my-company --site my-website -o leads.csv
-```
-
-#### `zerodeploy form delete <name> --org <org> --site <site>`
-
-Delete a form and all its submissions.
-
-**Options:**
-- `--force` - Skip confirmation prompt
-
-```bash
-zerodeploy form delete contact --org my-company --site my-website
-```
-
-#### `zerodeploy form notify <name> --org <org> --site <site>`
-
-Configure email notifications for form submissions.
-
-**Options:**
-- `--email <email>` - Email address to receive notifications
-- `--disable` - Disable email notifications
-
-```bash
-# Enable notifications
-zerodeploy form notify contact --org my-company --site my-website --email alerts@example.com
-
-# Disable notifications
-zerodeploy form notify contact --org my-company --site my-website --disable
-```
-
-### Account
-
-#### `zerodeploy account email <email>`
-
-Set or update your email address for deployment notifications.
-
-```bash
-zerodeploy account email you@example.com
-```
-
-#### `zerodeploy account delete`
-
-Permanently delete your account and all associated data.
-
-**Options:**
-- `--force` - Skip confirmation prompts
-
-```bash
-zerodeploy account delete
-```
-
-**Warning:** This permanently deletes your account, all organizations, sites, deployments, and custom domains.
-
-## Configuration File
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate with GitHub OAuth |
+| `logout` | Clear stored authentication token |
+| `whoami` | Display current logged-in user |
+| `usage` | Show current usage and plan limits |
+| `org list/create/delete` | Manage organizations |
+| `site list/create/delete/rename` | Manage sites |
+| `site stats` | View site traffic analytics |
+| `site subdomain` | Change site subdomain |
+| `deploy` | Deploy a directory to a site |
+| `deploy promote` | Promote a preview deployment to production |
+| `deployments list/show/logs` | View deployment history and logs |
+| `rollback` | Roll back to a previous deployment |
+| `domain add/verify/list/remove` | Manage custom domains |
+| `domain redirect` | Set www/apex redirect mode |
+| `token create/list/delete` | Manage API and deploy tokens |
+| `form list/export/delete/notify` | Manage form submissions |
+| `billing usage/bills/adjustments` | View billing information |
+| `account email/delete` | Manage account settings |
+| `init` | Create `zerodeploy.json` config file |
+| `update` | Update CLI to the latest version |
+| `inspect` | Output command metadata as JSON |
+
+Most data-returning commands support `--json` for machine-readable output.
+
+For detailed documentation on each command, see the [CLI Reference](https://zerodeploy.dev/docs/cli).
+
+## Configuration
 
 Create a `zerodeploy.json` in your project root:
 
@@ -437,27 +70,6 @@ Create a `zerodeploy.json` in your project root:
 zerodeploy init --org my-company --site my-website
 ```
 
-The CLI auto-detects your framework and creates an appropriate config:
-
-```json
-{
-  "org": "my-company",
-  "site": "my-website",
-  "dir": "dist",
-  "build": "npm run build"
-}
-```
-
-**Config Options:**
-
-| Field | Description |
-|-------|-------------|
-| `org` | Organization slug |
-| `site` | Site slug |
-| `dir` | Build output directory |
-| `build` | Build command (used with `--build` flag) |
-| `install` | Install command (used with `--install` flag) |
-
 Then deploy with just:
 
 ```bash
@@ -465,183 +77,31 @@ zerodeploy deploy           # deploy only
 zerodeploy deploy --build   # build + deploy
 ```
 
-CLI flags always take precedence over config values.
-
-## 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
+## CI/CD
 
-### SPA Support
+For GitHub-based CI/CD, use the [GitHub App integration](https://zerodeploy.dev/docs/github) which auto-deploys on push and creates preview deployments for PRs — no configuration needed.
 
-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:**
+For other CI/CD systems, create a deploy token and set the `ZERODEPLOY_TOKEN` environment variable:
 
 ```bash
-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`:**
+zerodeploy token create "CI Deploy" --org my-company --site my-website
 
-```yaml
-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:**
-
-```yaml
-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
+# Then in your CI pipeline:
+npx @zerodeploy/cli deploy my-site --org my-org
 ```
 
-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:
+## Updating
 
 ```bash
-# 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
+zerodeploy update
 ```
 
-## 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
+The CLI checks for updates automatically after each command (once per day) and shows a banner if a new version is available.
 
-## Links
+## Documentation
 
-- [Documentation](https://zerodeploy.dev/docs)
-- [Support](https://zerodeploy.dev/support)
+- [Quick Start](https://zerodeploy.dev/docs/quickstart)
+- [CLI Reference](https://zerodeploy.dev/docs/cli)
+- [Custom Domains](https://zerodeploy.dev/docs/cli/domain)
+- [GitHub Integration](https://zerodeploy.dev/docs/github)
+- [Redirects & Rewrites](https://zerodeploy.dev/docs/redirects)