---

What is goscaf?

goscaf generates opinionated, production-quality Go project boilerplate via an interactive CLI. Stop copy-pasting skeleton code between projects. Start with:

• Graceful shutdown with OS signal handling
• Structured JSON logging (slog, zerolog, or zap)
• Your choice of HTTP framework (gin, fiber, chi, echo, gorilla/mux)
• Your choice of Database driver (postgres, mysql, sqlite, mongo, gorm)
• Viper-powered config with .env support
• Optional infra clients: Redis, Kafka, NATS
• Multi-stage distroless Dockerfile + docker-compose
• Makefile, GitHub Actions CI, golangci-lint - ready to go on day one

---

Install

Go install

go install github.com/iyashjayesh/goscaf@latest

Homebrew (coming soon)

brew install goscaf-dev/tap/goscaf

From source

git clone https://github.com/iyashjayesh/goscaf.git
cd goscaf
make install

---

Usage

Interactive mode

goscaf init my-api

Sample prompt flow:

? Module name: (github.com/your-org/my-api)
? Go version: (1.25.0)
? HTTP framework: gin
? Structured logger: slog (stdlib)
? Add Viper for config & env management? (Y/n)
? Add Redis client (go-redis)? (y/N)
? Add Kafka client (franz-go)? (y/N)
? Add NATS client? (y/N)
? Database driver: (none)
? Add Dockerfile + docker-compose? (Y/n)
? Add Makefile? (Y/n)
? Add GitHub Actions CI? (Y/n)
? Add golangci-lint config? (Y/n)
? Add Swagger/OpenAPI scaffold? (y/N)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Scaffolding project: my-api
  Module:    github.com/your-org/my-api
  Go:        1.25.0
  Framework: gin
  Logger:    slog
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✓ cmd/main.go
  ✓ go.mod
  ✓ .gitignore
  ✓ .env.example
  ✓ internal/config/config.go
  ✓ internal/handler/handler.go
  ✓ internal/server/server.go
  ✓ Dockerfile
  ✓ docker-compose.yml
  ✓ Makefile
  ✓ .github/workflows/ci.yml
  ✓ .golangci.yml
  → Running go mod tidy...
  ✓ go mod tidy

  ✔ Project created successfully!

  Next steps:
    cd my-api
    cp .env.example .env
    make docker-up
    make run

Non-interactive / CI mode

goscaf init my-api --defaults
goscaf init my-api --framework fiber --logger zap --redis --kafka --docker

---

Flags

Flag	Default	Description
--module	""	Go module path
--go-version	1.25.0	Go version (1.23, 1.24, 1.25)
--framework	gin	HTTP framework (gin|fiber|chi|echo|gorilla|none)
--logger	slog	Structured logger (slog|zerolog|zap)
--viper	true	Add Viper for config & env management
--redis	false	Add Redis client (go-redis/v9)
--kafka	false	Add Kafka client (franz-go)
--nats	false	Add NATS client
--db	none	Database driver (postgres|mysql|sqlite|mongo|gorm|none)
--docker	true	Add Dockerfile + docker-compose
--makefile	true	Add Makefile
--github	true	Add GitHub Actions CI
--lint	true	Add golangci-lint config
--swagger	false	Add Swagger/OpenAPI scaffold
--defaults	false	Skip all prompts, use recommended defaults
--output	.	Output directory

---

Generated Project Structure

my-api/
├── cmd/
│   └── main.go                  # Entrypoint with graceful shutdown
├── internal/
│   ├── config/
│   │   └── config.go            # Viper (or stdlib) config loader
│   ├── server/
│   │   └── server.go            # HTTP server for chosen framework
│   └── handler/
│       └── handler.go           # HTTP handlers
├── pkg/
│   ├── db/db.go                 # (if selected) Database connection wrapper
│   ├── redis/redis.go           # (if selected) go-redis wrapper
│   ├── kafka/kafka.go           # (if selected) franz-go producer+consumer
│   └── nats/nats.go             # (if selected) NATS client wrapper
├── .github/
│   └── workflows/ci.yml
├── .env.example
├── .gitignore
├── .golangci.yml
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── Makefile

---

Generated Makefile Targets

Target	Description
make run	go run ./cmd/main.go
make build	Build binary to bin/<name>
make test	go test -race -cover ./...
make test-coverage	Generate coverage.html report
make lint	golangci-lint run ./...
make fmt	gofmt -s -w . && goimports -w .
make tidy	go mod tidy
make docker-up	docker compose up -d
make docker-down	docker compose down
make docker-logs	docker compose logs -f app
make clean	Remove bin/, coverage.*
make install-tools	Install golangci-lint + goimports

---

Supported Frameworks

Flag value	Import path
gin	github.com/gin-gonic/gin
fiber	github.com/gofiber/fiber/v2
chi	github.com/go-chi/chi/v5
echo	github.com/labstack/echo/v4
gorilla	github.com/gorilla/mux
none	stdlib net/http

---

Supported Databases

Flag value	Driver / Library
postgres	github.com/jackc/pgx/v5
mysql	github.com/go-sql-driver/mysql
sqlite	modernc.org/sqlite
mongo	go.mongodb.org/mongo-driver
gorm	gorm.io/gorm (with Postgres driver)
none	No database scaffolded

---

Contributing

# Clone and build
git clone https://github.com/iyashjayesh/goscaf.git
cd goscaf
make build

# Run the smoke test
make smoke-test

PRs welcome! Please open an issue first for major changes.