verda-goapp-template

Skip the boilerplate. Ship Go services and CLIs that are production-grade on day one.

A verdactl project template that scaffolds complete Go applications — wired for observability, structured logging, graceful shutdown, configuration, and testability — in a single command.

Why use this template

Most Go starters give you main.go and a go.mod. You still spend a week adding logging, metrics, tracing, config loading, graceful shutdown, a test harness, a CLI framework, and an opinion about how to lay it all out. Every service ends up slightly different.

This template gives you all of that, pre-assembled and consistent across every project:

• One template, four server flavors. Pick gin, http, grpc, or grpc-gateway at generate time and get a correctly wired server — no hand-stitching HTTP gateways to gRPC backends.
• Observability out of the box. OpenTelemetry traces, Prometheus metrics, structured logs (zap), and a /healthz endpoint — already connected to your request path. Toggle with a single with_observability flag.
• Interactive CLIs, not just flag parsers. The cli variant scaffolds Cobra subcommands that work fully from flags and fall back to a Bubble Tea wizard when run interactively — no duplicate prompt/flag code.
• The full options pattern. Complete → Validate → Run, shared Factory, IOStreams, CommandGroups, typed handlers. The same conventions whether you're writing a web service or a DevOps tool.
• Consistent across a whole org. Every generated project lays out the same way, uses the same lifecycle, and reads the same way in code review. New engineers are productive on day one across any repo.
• Built on verdagostack v1.3.3. Battle-tested shared libraries for servers, options, TUI, logging, metrics, and middleware — you get the upstream fixes for free.

If you're starting more than one Go service a year, this template pays for itself the first time you use it.

Quick start

verdactl gen new \
  --template github.com/verda-cloud/verda-goapp-template \
  --module github.com/your-org/your-app \
  --out ./your-app

cd your-app
make run

That's it — you have an app with working health checks, metrics, traces, logs, and a clean lifecycle. Add your business logic in internal/<app>/handler/ (webapp) or internal/<app>/cmd/<subcommand>/ (CLI).

verdactl walks you through the placeholder prompts interactively, or pass them non-interactively with repeated --define key=value.

What gets generated

Webapp (app_type=webapp)

server_type	What it wires
gin	Gin engine, typed handlers via ginx, OTel middleware
http	Standard library net/http, for minimal-dep services
grpc	gRPC server + health + reflection, ready for protobuf services
grpc-gateway	gRPC + HTTP reverse-proxy gateway, one binary serves both

Layout:

cmd/<app>/            Entry point and app.NewApp wiring
internal/<app>/       Server implementation + handlers
configs/<app>.yaml    Default configuration file

CLI (app_type=cli)

cmd/<app>/main.go
internal/<app>/cmd/              Root + subcommands (cobra + wizard)
internal/<app>/cmd/util/         Factory, IOStreams, CommandGroups
internal/<app>/options/          Shared CLI options (log, user, config)

You declare subcommands up front in the subcommands placeholder — each one is scaffolded with flags and a matching Bubble Tea wizard step so users can run it either way.

Placeholders

Configured in verda-gen.yaml:

Name	Type	Choices / Default	Applies to
app_type	enum	webapp | cli — default webapp	all
server_type	enum	gin | http | grpc | grpc-gateway	webapp
description	string	free-form — default "A new Go service"	all
with_observability	bool	default true	webapp
subcommands	list	name, description per entry	cli

Working on the template itself

This repo is not a runnable Go app — it's a tree of .tmpl files rendered by verdactl. When editing, change .tmpl files and verda-gen.yaml together when paths move, then refresh samples and catch render errors:

./test/run.sh   # renders tmp/webapp-gin, tmp/webapp-http, tmp/cli-tool, tmp/cli-minimal

The exhaustive specification for every generated file lives in requirements.md. AI coding agents should start with AGENTS.md.