Quick Start

Prerequisites

• Go 1.22+
• Docker running locally

Install

go install github.com/previewctl/previewctl-cli@latest

Verify the installation:

previewctl --help

Initialize a project

Navigate to your project root and run:

previewctl init

This creates a .previewctl/ directory with a default preview.yml config file.

Configure your services

Edit .previewctl/preview.yml to define your stack:

version: 1

preview:
  ttl: 24h

services:
  api:
    build:
      type: dockerfile
      context: .
      dockerfile: Dockerfile
    port: 8080
    env:
      DATABASE_URL: postgresql://postgres:${services.postgres.env.POSTGRES_PASSWORD}@${services.postgres.host}:5432/mydb
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    port: 5432
    env:
      POSTGRES_DB: mydb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${Generate(16)}

Bring it up

previewctl up

PreviewCtl will:

1. Validate your config
2. Resolve service dependencies (DAG ordering)
3. Build your services (Dockerfile, Nixpacks, or Railpack)
4. Create a Docker network
5. Start all containers in the correct order

Check your environments

previewctl list

Output:

ID        NAME              BRANCH   STATUS   WORKSPACE              CREATED
abc123    my-project-main   main     active   /home/user/my-project  2026-03-11 10:00:00

Clean up

Stop the environment (preserves data so you can up again later):

previewctl down my-project-main

Or permanently delete it:

previewctl delete my-project-main

This stops all containers, removes the network, and cleans up the local database records.

Next steps

• Read the Configuration reference for all preview.yml options
• Explore individual commands in detail
• Pass secrets with previewctl up --secret STRIPE_KEY=sk_test_...