Preview CLI

Preview CLI

dst preview subcommands. All commands respect the DESTESI_API_KEY and DESTESI_WORKSPACE env vars for stateless CI use.

Commands at a glance

Command	Purpose
dst preview create	Register a new preview (tarball or GitHub source).
dst preview upsert	Idempotent create/redeploy keyed by (workspace, pr_number) — use in CI.
dst preview wait	Block until healthy (exit 0) / failed (1) / timeout (2).
dst preview show	Show details by id or PR number. Supports -o url / -o id / -o json / -o status.
dst preview list	List previews in the active workspace.
dst preview redeploy	Tear down and rebuild in place (keeps the same id / URL).
dst preview delete	Soft-delete a preview. Controller cleans up pod + snap.
dst preview logs	Stream container logs (--container, --tail, -f/--follow).

dst preview create

Register a new preview. Use --from-dir for local tarball (iteration) or --repo / --branch / --third-party-app for GitHub.

dst preview create \
  --from-dir    ./app \
  --name        local-test \
  --from-remote conn_abc \
  --env         'DATABASE_URL=${postgres.dsn}' \
  --env-secret  NEXTAUTH_SECRET=$(openssl rand -hex 32) \
  --public-service app --public-port 3000 \
  --ttl         24h

Key flags

• --from-dir <path> — tar a local directory containing docker-compose.yml and upload it.
• --repo <owner/name> — pull a GitHub source. Requires --third-party-app <id> — your workspace’s Connect GitHub connection id.
• --from-remote <name|id> — Snap remote to fork the database from.
• --from-snap <id> — fork from a specific snap branch (power users; prefer --from-remote).
• --env NAME=value / --env-secret NAME=value — repeatable. Value may contain ${postgres.*} refs.
• --public-service / --public-port — which compose service+port gets the public NodePort. Auto-detected if omitted.
• --ttl <duration> — auto-teardown after N (default 24h).

dst preview upsert

Same flags as create, plus --pr-number (required). Keyed by (workspace, pr_number) — safe to call on every synchronize without accumulating previews.

dst preview upsert \
  --repo            owner/repo \
  --branch          feat/x   --commit $SHA \
  --third-party-app <github-app-id> \
  --pr-number       42  --pr-title "..."  --pr-url https://github.com/... \
  -o id

dst preview wait

Blocks until the preview reaches a terminal state. Exit code is the outcome.

dst preview wait prev_abc --timeout 10m
# → https://prev-abc.your-workspace.preview.destesi.io

• Exit 0 — healthy. Stdout is the public URL.
• Exit 1 — failed. Stderr has the last error.
• Exit 2 — timeout. The preview may still reach healthy later.
• Exit 3 — the preview was deleted while waiting.

dst preview show / list

dst preview show prev_abc -o url
# → https://prev-abc.your-workspace.preview.destesi.io

dst preview show --by-pr 42 -o id
# → prev_abc

dst preview list --status healthy

dst preview redeploy / delete

dst preview redeploy prev_abc
# same id, fresh pod + snap fork

dst preview delete --by-pr 42
# soft-delete; controller cleans up pod + snap

Next

GitHub Actions workflow

Troubleshooting