CLI

PullPreview CLI

Use the pullpreview binary for local debugging, manual deployments, and provider validation outside GitHub Actions.

Install

Download a release binary from GitHub Releases and add it to your PATH, or build from source.

Build from source with the repo toolchain:

mise exec -- go run ./cmd/pullpreview --help
mise exec -- go build -o pullpreview ./cmd/pullpreview

Basic commands

# Deploy a local project
pullpreview up ./path/to/app --name pullpreview-local --instance-type small --region us-east-1

# List deployments created by PullPreview
pullpreview list
pullpreview list my-org/my-repo

# Destroy a deployment by instance name
pullpreview down --name pullpreview-local

Other command:

pullpreview github-sync ./path/to/app

Deployment target flags

Use --deployment-target to choose the runtime:

• compose is the default
• helm bootstraps k3s and deploys a Helm chart

Compose example

pullpreview up ./examples/workflow-smoke \
  --name pullpreview-local-compose \
  --deployment-target compose \
  --compose-files docker-compose.yml \
  --compose-options=--build \
  --proxy-tls web:8080

Helm example

pullpreview up ./examples/openproject \
  --name pullpreview-local-helm \
  --deployment-target helm \
  --chart ./chart \
  --chart-values values-preview.yaml \
  --chart-set 'baseUrl={{pullpreview_url}}' \
  --proxy-tls '{{release_name}}-web:80'

Helm rules:

• --chart is required.
• --proxy-tls is required.
• --registries is not supported.
• Custom --compose-files and --compose-options are not supported.

Hetzner local usage

For provider: hetzner, set:

• PULLPREVIEW_PROVIDER=hetzner
• HCLOUD_TOKEN
• HETZNER_CA_KEY

Example:

PULLPREVIEW_PROVIDER=hetzner \
HETZNER_CA_KEY="$(cat ~/.ssh/hetzner_ca_key)" \
HCLOUD_TOKEN=... \
pullpreview up ./path/to/app \
  --deployment-target helm \
  --chart ./charts/my-app \
  --proxy-tls '{{release_name}}-web:80' \
  --region nbg1 \
  --image ubuntu-24.04 \
  --instance-type cpx21

Generate a compatible CA key with:

ssh-keygen -t rsa -b 3072 -m PEM -N "" -f ~/.ssh/hetzner_ca_key

If you keep values in a .env file, load them first:

set -a
. ./.env
set +a

Notes

• up accepts a local path or a Git URL as app_path.
• list optionally accepts org/repo as a positional argument.
• down accepts either normalized instance names or existing pullpreview-* context-style names.
• --region, --image, and --instance-type are the provider sizing/location knobs exposed by both the CLI and the GitHub Action.