feat(cli): add --print-sample-config flag

Print contrib/pgwd.conf.example to stdout before config load so operators
without the example file on disk can bootstrap /etc/pgwd/pgwd.conf.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hrodrig

CHANGELOG.md

@@ -6,6 +6,10 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Histor
 
 ## [Unreleased]
 
+### Added
+
+- **`pgwd --print-sample-config`** — writes annotated sample config to stdout (same as `contrib/pgwd.conf.example`).
+
 ## [0.6.8] - 2026-06-10
 
 ### Security

README.md

@@ -127,7 +127,7 @@ pgwd loads settings from (in order): **config file** → **environment variables
 | Environment | `PGWD_*` |
 | CLI | `-flag` |
 
-**Config file** (YAML) — keys match `-flag` and `PGWD_*` env vars. See `contrib/pgwd.conf.example`. Use `databases:` for one or more Postgres (canonical). Legacy `db:` is deprecated and will be removed in v1.0. For kube.postgres, use `db:` until per-db kube support exists.
+**Config file** (YAML) — keys match `-flag` and `PGWD_*` env vars. See `contrib/pgwd.conf.example` (or **`pgwd --print-sample-config > /etc/pgwd/pgwd.conf`** when the example file is not on disk). Use `databases:` for one or more Postgres (canonical). Legacy `db:` is deprecated and will be removed in v1.0. For kube.postgres, use `db:` until per-db kube support exists.
 
 ```bash
 # Use default path /etc/pgwd/pgwd.conf
@@ -522,6 +522,7 @@ All parameters can be set via **config file**, **CLI**, or **environment variabl
 
 | CLI | Env | Description |
 |-----|-----|-------------|
+| `--print-sample-config` | — | Print annotated sample config to **stdout** and exit (same as `contrib/pgwd.conf.example`). |
 | `-config` | `PGWD_CONFIG` | Config file path (YAML). Default `/etc/pgwd/pgwd.conf`. See `contrib/pgwd.conf.example`. |
 | `-db-url` | `PGWD_DB_URL` | PostgreSQL connection URL (required). With `-kube-postgres`, use host localhost and port matching `-kube-local-port`. |
 | `-kube-postgres` | `PGWD_KUBE_POSTGRES` | Connect via port-forward (client-go): `namespace/type/name` (e.g. `default/svc/postgres`). Requires kubeconfig. |

cmd/pgwd/main.go

@@ -18,6 +18,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/hrodrig/pgwd/contrib"
 	"github.com/hrodrig/pgwd/internal/checker"
 	"github.com/hrodrig/pgwd/internal/config"
 	"github.com/hrodrig/pgwd/internal/httpsrv"
@@ -69,6 +70,16 @@ func handleVersion() {
 	}
 }
 
+// handlePrintSampleConfig writes the annotated example config to stdout and exits when requested.
+func handlePrintSampleConfig() {
+	for _, arg := range os.Args[1:] {
+		if arg == "--print-sample-config" || arg == "-print-sample-config" {
+			fmt.Print(contrib.SampleConf())
+			os.Exit(0)
+		}
+	}
+}
+
 // parseFlags registers pgwd CLI flags on cfg, parses os.Args, and returns whether
 // -version was set. Call after loading config from file/env so flag values override
 // those sources (see config.FinalizeAfterFlags). When true, the caller should
@@ -724,6 +735,7 @@ func logConfigTrace(path string, configLoaded bool, hasCLIArgs bool) {
 // once or on a ticker, and serve HTTP /metrics when configured.
 func main() {
 	handleVersion()
+	handlePrintSampleConfig()
 
 	cfg, loaded, configPath := loadAndParseConfig()
 	applyDBURLOverride(&cfg)

cmd/pgwd/main_test.go

@@ -56,6 +56,19 @@ func runBinary(args ...string) (stdout, stderr string, exitCode int) {
 	return stdout, stderr, exitCode
 }
 
+func TestMain_PrintSampleConfig(t *testing.T) {
+	stdout, stderr, code := runBinary("--print-sample-config")
+	if code != 0 {
+		t.Errorf("pgwd --print-sample-config: exit code %d, want 0", code)
+	}
+	if stdout == "" || !strings.Contains(stdout, "client:") {
+		t.Errorf("pgwd --print-sample-config: stdout %q does not contain sample config", stdout)
+	}
+	if stderr != "" {
+		t.Errorf("pgwd --print-sample-config: expected empty stderr, got %q", stderr)
+	}
+}
+
 func TestMain_Version(t *testing.T) {
 	stdout, _, code := runBinary("-version")
 	if code != 0 {

contrib/sample.go

@@ -0,0 +1,11 @@
+package contrib
+
+import _ "embed"
+
+//go:embed pgwd.conf.example
+var sampleConf []byte
+
+// SampleConf returns the annotated example configuration (same as contrib/pgwd.conf.example).
+func SampleConf() string {
+	return string(sampleConf)
+}

contrib/sample_test.go

@@ -0,0 +1,16 @@
+package contrib
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSampleConf(t *testing.T) {
+	s := SampleConf()
+	if !strings.Contains(s, "client:") {
+		t.Fatal("missing client key")
+	}
+	if !strings.Contains(s, "databases:") {
+		t.Fatal("missing databases block")
+	}
+}