CLI

One command, any Dockerfile, a preview URL. Use it to trigger deploys without a Git push — great for CI pipelines and ad-hoc previews.

Install

bash
npm i -g previewdrop
# or
npx previewdrop --help

Source and full README: npmjs.com/package/previewdrop.

Authenticate

bash
previewdrop login
# Opens a browser, creates a token, saves to ~/.previewdrop/config

For CI, skip the browser flow and use a token directly:

bash
export PREVIEWDROP_TOKEN=pd_live_xxx  # create in Dashboard → Settings → API tokens
previewdrop list

Commands

`previewdrop deploy`

Create a preview. Pass a project ID and a branch to build, or let it read from your current Git state.

bash
previewdrop deploy \
  --project prj_abc123 \
  --branch feature/checkout-v2 \
  --commit a1b2c3d4    # optional, defaults to branch HEAD

# Or, inside a git checkout:
previewdrop deploy --project prj_abc123   # uses current branch + HEAD SHA

`previewdrop list`

Show recent deployments in your workspace.

bash
previewdrop list
previewdrop list --project prj_abc123 --status ready
previewdrop list --json | jq '.[] | {id, url, status}'

`previewdrop status`

Check one deployment. Handy in CI to poll until ready.

bash
previewdrop status dep_xyz
# => status: ready
# => url:    https://feature-checkout-v2-abc.previews.previewdrop.dev

previewdrop status dep_xyz --wait    # blocks until terminal state

`previewdrop logs`

Stream build logs or runtime stdout. Tail with -f.

bash
previewdrop logs dep_xyz           # build logs
previewdrop logs dep_xyz --runtime # container stdout/stderr
previewdrop logs dep_xyz -f        # follow

`previewdrop destroy`

bash
previewdrop destroy dep_xyz
previewdrop destroy --branch feature/checkout-v2  # all previews on this branch

Use in CI

For most teams, the Git-provider integration auto-triggers previews on every push — you don't need the CLI. Use the CLI when you want to gatethe preview on your own pipeline (e.g. only after tests pass) or when you're deploying from a repo that isn't connected to a provider.

GitHub Actions

yaml
name: Preview
on: pull_request
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test          # gate the preview on tests
      - run: npx previewdrop deploy --project $PD_PROJECT --wait
        env:
          PREVIEWDROP_TOKEN: ${{ secrets.PREVIEWDROP_TOKEN }}
          PD_PROJECT: ${{ secrets.PD_PROJECT }}

GitLab CI

yaml
preview:
  stage: deploy
  image: node:20
  script:
    - npx previewdrop deploy --project $PD_PROJECT --wait
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    PREVIEWDROP_TOKEN: $PREVIEWDROP_TOKEN

CircleCI

yaml
jobs:
  preview:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run: npx previewdrop deploy --project $PD_PROJECT --wait

Environment variables (CLI)

PREVIEWDROP_TOKEN — auth token. Required in CI, set by login elsewhere.
PREVIEWDROP_API — override the API base URL (useful for self-hosted).
PREVIEWDROP_NO_COLOR=1 — disable ANSI colour output.

Output formats

Every command accepts --json for machine-parseable output. Pipe through jq to slot into shell scripts.

bash
URL=$(previewdrop deploy --project $PD_PROJECT --wait --json | jq -r .url)
curl -sSf "$URL/health"

Full CLI reference — every flag, every exit code — is on the npm README. File bugs at github.com/.../previewdrop/issues.