PreviewDrop CLI

A live URL for every branch. Any app, any stack.

Command-line companion to previewdrop.dev — isolated preview environments for every branch you push. Point PreviewDrop at a Dockerfile (Django, Rails, Laravel, FastAPI, Next.js, Go, Rust — anything) and get a shareable HTTPS URL in under 60 seconds. Open a PR and the URL lands as a bot comment. Merge the PR and the preview cleans itself up.

This CLI lets you trigger deploys, watch builds, tail logs, and destroy previews straight from your terminal — or wire it into CI/CD.

Install

# Global
npm install -g previewdrop

# Or run ad-hoc
npx previewdrop <command>

Requires Node.js 18+

Quick start

You need a PreviewDrop account and at least one connected repo. Sign up free at previewdrop.dev and install the GitHub App — takes under a minute. Then:

# 1. Authenticate the CLI (opens your browser)
previewdrop login

# 2. Find your project ID
previewdrop list projects

# 3. Deploy any branch and wait for a live URL
previewdrop deploy <project-id> --branch feat/new-ui --wait

You'll see something like:

✓ Deployment started: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Preview URL: https://prv-a8c2f9.previews.previewdrop.dev
⠼ Status: building…
✓ Deployment ready!
  https://prv-a8c2f9.previews.previewdrop.dev

That URL is a full isolated environment. Share it with designers, PMs, QA, or clients — no VPN, no staging contention, no localhost tunneling.

Commands

login — authenticate

previewdrop login [--key <api-key>] [--host <url>]

Opens your browser to generate an API key and stores it locally (under ~/.config/previewdrop). For CI, pass a token directly:

previewdrop login --key $PREVIEWDROP_API_KEY

list — discover projects and deployments

previewdrop list projects
previewdrop list deployments <project-id> [--limit <n>]

deploy — trigger a preview

previewdrop deploy <project-id> [--branch <branch>] [--wait]

• --branch — any branch name (defaults to the project's configured default branch)
• --wait — block until the deployment reaches a terminal state. Exits 0 on ready, 1 on failed/stopped/expired. Makes this safe to drop into CI.

status — inspect a deployment

previewdrop status <deployment-id> [--watch]

Possible states: queued · building · deploying · ready · failed · stopped · expired.

--watch polls until a terminal state is reached, showing the live status inline.

logs — build + runtime logs

previewdrop logs <deployment-id>            # build log (nixpacks / Dockerfile output)
previewdrop logs <deployment-id> --runtime  # container stdout/stderr
previewdrop logs <deployment-id> --runtime --tail 500

Build logs include auto-detected diagnostics for common failures (missing env vars, lockfile conflicts, port binding issues, unsupported runtimes). Runtime logs are colour-coded by severity so errors jump off the page.

destroy — tear down a preview

previewdrop destroy <deployment-id> [--yes]

Stops the container and marks the deployment as stopped. --yes skips the confirmation prompt for scripts.

MCP Server (AI Assistant Integration)

PreviewDrop ships an MCP (Model Context Protocol) server so AI assistants like Claude Desktop, Cursor, and any MCP-compatible client can manage your preview environments with natural language.

Configure your AI assistant

Add PreviewDrop to your MCP client config (e.g. ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "previewdrop": {
      "command": "npx",
      "args": ["previewdrop", "mcp"],
      "env": {
        "PREVIEWDROP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available tools

Available tools: get_account · list_projects · list_deployments · get_deployment · deploy (with optional wait) · redeploy · destroy_deployment · get_build_logs · get_runtime_logs · create_project · get_github_app_install_url · deploy_repo · get_project_env_vars · set_project_env_vars

Run manually

# Uses API key from PREVIEWDROP_API_KEY env var
PREVIEWDROP_API_KEY=your-key npx previewdrop mcp

# Or use the stored key from `previewdrop login`
npx previewdrop mcp

You: Preview the Quick Invoice project on the current branch.

AI: [reads .git/config — remote origin = acme/quick-invoice] [calls deploy_repo — githubRepo: acme/quick-invoice, branch: feature/stripe-v2]

  Status: ready
  Preview URL: https://prv-7c1a3f2.previews.previewdrop.dev
  Built in 52s

**First-time setup with a new repo** — if the repo isn't in PreviewDrop yet, just ask:

You: Preview the acme/payments-api repo on branch feature/stripe.

AI: [calls create_project — githubRepo: acme/payments-api] Project created! ID: proj_f4e2a1c [calls deploy — projectId: proj_f4e2a1c, branch: feature/stripe, wait: true] Preview is live: https://prv-9a3c7f1.previews.previewdrop.dev

If the GitHub App isn't installed yet, the AI calls `get_github_app_install_url` automatically and gives you the direct link.

**Managing env vars via MCP** — ask the agent to set secrets before deploying:

You: Set DATABASE_URL and SECRET_KEY for the quick-invoice project, then redeploy.

AI: [calls get_project_env_vars — shows which keys are already configured] [calls set_project_env_vars — merges DATABASE_URL and SECRET_KEY, encrypted at rest] [calls redeploy — triggers a new deployment with the updated vars]

  Done! New deployment is live:
  https://prv-7c1a3f2.previews.previewdrop.dev

`get_project_env_vars` returns key names with values masked (`***`) so the agent can see what's configured without reading your secrets. `set_project_env_vars` merges the supplied keys into the project — existing vars not in the payload are preserved.

See the full [MCP docs](https://previewdrop.dev/docs/mcp) for details.

---

## CI/CD

The primary reason the CLI exists. Every preview gets a unique HTTPS URL, so your pipeline can post it to Slack, attach it to a GitHub PR comment, or feed it into Playwright / Cypress for end-to-end tests against a real environment.

### GitHub Actions

```yaml
name: Deploy preview
on: pull_request

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - run: npm install -g previewdrop
      - run: previewdrop login --key ${{ secrets.PREVIEWDROP_API_KEY }}

      - name: Deploy branch
        run: previewdrop deploy ${{ secrets.PROJECT_ID }} --branch ${{ github.head_ref }} --wait

PreviewDrop already posts a bot comment + commit status check when the GitHub App sees the PR — this Action is for cases where you need the URL inside another job (e.g. for E2E tests), or where you run CI on a different platform.

GitLab CI / Jenkins / CircleCI

The CLI is a plain Node binary with a well-defined exit code, so it drops into any CI. Store PREVIEWDROP_API_KEY as a secret and run:

npm install -g previewdrop
previewdrop login --key "$PREVIEWDROP_API_KEY"
previewdrop deploy "$PROJECT_ID" --branch "$BRANCH_NAME" --wait

Exit 0 = ready · Exit 1 = failed/stopped/expired.

What PreviewDrop runs

Anything PreviewDrop's build layer can auto-detect or containerise via a Dockerfile:

• Backends: Django · Rails · Laravel · FastAPI · Flask · Spring Boot · Go · Rust · Express · Fastify · Hono · Node · PHP
• Frontend / full-stack: Next.js · Astro · Vite · Nuxt · Remix · SvelteKit · Gatsby · Angular
• Web exports: Expo · React Native + react-native-web

No YAML. No Kubernetes. No build-pipeline edits. No per-service resource tuning — one flat workspace price covers everything.

Why PreviewDrop

• Every branch, not just PRs. Push a spike, get a URL. PR bot comments are included when you open one — but the preview doesn't wait for a PR to exist.
• Any Docker-based backend. The branch-preview gap Vercel and Netlify can't cover — Django, Rails, Laravel, FastAPI, Spring Boot. Anything you can run in a container.
• Flat per-workspace pricing. One bill for the team. No per-seat tax, no per-resource usage billing, no bill-shock on a busy sprint.
• Auto-expiring + password-protected URLs. Safe to share with clients or stakeholders — the preview self-destructs on a schedule you control.
• Zero config. Install the GitHub App, pick a repo. Push. Done.

Links

• Website & signup — previewdrop.dev
• Pricing — previewdrop.dev/pricing
• Docs — previewdrop.dev/docs
• Source — github.com/global-software-development-eu/previewdrop
• Issues — github.com/global-software-development-eu/previewdrop/issues
• Support — [email protected]

License

MIT — © 2026 Global Software Development SRL