got

GOT CLI

Go Templatify

General-purpose Go/Fiber project generator.

What is GOT?

GOT is a command-line generator for starting and extending Go services built with Fiber and GORM. It creates conventional project layers while leaving application-specific business logic in your hands.

Why GOT?

GOT provides repeatable project structure and removes routine setup work while keeping the generated Go source readable and under your control. It is intended for real services rather than throwaway demos: generated projects can be built, tested, and extended using normal Go tooling.

Features

• Generate a standard API, a deployable microservice, or a multi-service workspace.
• Scaffold routes, handlers, services, repositories, schemas, and entities.
• Inspect PostgreSQL or SQL Server schemas and generate working CRUD layers.
• Add methods to existing features, JWT authentication, file uploads, and OpenAPI/Swagger UI.
• Generate structured JSON logging, configuration with environment overrides, and, for microservices, health checks, graceful shutdown, and a Dockerfile.
• Share logging and HTTP middleware across workspace services through a libs module.
• Check local tools and generated projects with got doctor.

See Current Features for a concise summary and known gaps, and User-Guide.md for detailed workflows.

Requirements

• Go 1.26 or newer, to install GOT and to build generated projects. Go 1.25 no longer receives security fixes.
• A PostgreSQL, MySQL, or SQL Server database for generated services to connect to at startup.
• Docker (optional), for container builds and the quick start database below.

Installation

go install github.com/gotcli/got@latest
got version

If got is not found, add the Go binary directory to PATH, for example in zsh:

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.zshrc
source ~/.zshrc

Release binaries may also be provided on the repository's Releases page; use only artifacts published there and verify any supplied checksums.

Quick Start

Create a standard PostgreSQL API:

got init --name catalog --module example.com/catalog --architecture standard --db pg
cd catalog
go test ./...

A generated service connects to its database at startup and exits if it cannot. Start a local PostgreSQL that matches the defaults in config.yml, then run the service:

docker run -d --name catalog-db -p 5432:5432 \
  -e POSTGRES_USER=app_user -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=app_db \
  postgres:16-alpine

CATALOG_DB_PASSWORD=secret go run .
curl http://127.0.0.1:3000/api

Run got init without flags for an interactive setup.

Configuration

Generated services read config.yml from the project root. Any key can be overridden by an environment variable prefixed with the last element of the module path, upper-cased, with - and . replaced by _. For module example.com/catalog, DB_PASSWORD becomes CATALOG_DB_PASSWORD; for example.com/platform/order-service, it becomes ORDER_SERVICE_DB_PASSWORD.

Keep secrets such as DB_PASSWORD and JWT secrets out of config.yml; the generated .gitignore excludes it from version control.

Example Commands

# Projects
got init
got init service --architecture microservice
got init workspace --name platform --module example.com/platform --services order,auth --db pg

# Inside a generated service
got generate crud
got generate crud --tables invoices --dry-run
got api --name users
got add method --folder users --name Approve --http-method PATCH
got add auth --jwt
got add upload
got add swagger
got doctor --project
got routes
got config

# Inside a workspace root (routes, config, and upgrade also work here)
got add service payment
got doctor --project

# Hexagonal projects: add a migration, then apply pending migrations
got add migration add_products_name_index
go run ./cmd migrate

# Bring a project generated by an older GOT version up to date
got upgrade --dry-run
got upgrade

In CI or scripts, or with --no-input, GOT never prompts: it fails and lists every missing flag. Supply the CRUD inspection password through GOT_DB_PASSWORD instead of the masked prompt.

Use got <command> --help before running a generator to review its flags and defaults. Existing files are never overwritten, and a failed project generation removes the partially created directory.

Architecture

Generated services follow a layered structure: routes call handlers, handlers call services, and services call repositories. Standard mode creates a single API; microservice mode adds health endpoints (/health/live, /health/ready), graceful shutdown, HTTP timeouts, and a multi-stage distroless Dockerfile.

Workspace mode creates independently buildable microservices that share common infrastructure code:

platform/
├── go.work                 # services/* and libs
├── got-workspace.json      # manifest used by "got add service"
├── Makefile                # make test | vet | tidy across services
├── libs/                   # shared module: logger, middleware
├── services/
│   ├── order-service/      # own go.mod, config.yml, Dockerfile
│   └── auth-service/
└── deploy/
    └── compose.yml         # one container per service, ports 3001+

Hexagonal mode (got init --architecture hexagonal --db pg) generates a ports and adapters layout for teams that keep business logic independent of frameworks:

shop/
├── cmd/main.go                   # entry point: serve (default) or migrate
├── internal/
│   ├── app.go                    # wiring
│   ├── domain/<entity>/          # business logic + unit tests with in-memory fakes
│   ├── port/inbound/             # service interfaces + registry_*.go
│   ├── port/outbound/            # repository interfaces + registry_*.go
│   ├── adapter/inbound/          # fiber (HTTP), command (CLI), rabbitmq
│   ├── adapter/outbound/         # postgres, http, rabbitmq, redis
│   ├── model/                    # entities, request and response models
│   └── migration/postgres/       # <version>_<table>.go, run with "go run ./cmd migrate"
└── utils/                        # config and logger

got generate crud writes every layer for each table, registers it in the port registries and routes, and adds an idempotent migration reconstructed from the table (unique constraints, foreign keys, and indexes are not included). got add swagger and got add auth --jwt place their code in the HTTP adapter (and utils/auth), and got add migration <name> creates the next numbered migration. got api and got add upload|method do not support hexagonal projects yet.

Each service requires the shared module through a local replace directive, so services build with or without go.work. Build and start every service with:

docker compose -f deploy/compose.yml up --build

Workspaces created by GOT v1.0.4 or earlier keep their layout (services at the root, compose.yml at the root); got add service follows it there.

Use --shared-module and --shared-version with got init workspace when the shared module is published from a separate repository; services then require that published version instead of the local libs directory. Services never share entities or database repositories.

Database Support

Project generation supports PostgreSQL, MySQL, and SQL Server through GORM. Schema inspection and CRUD generation support PostgreSQL and SQL Server. See the status table for stability details.

Documentation

Detailed installation, configuration, workflows, and troubleshooting are in the GOT CLI User Guide. Current Features summarizes available commands, generated capabilities, and known gaps. See the Changelog before upgrading. CLI help is the authoritative reference for the installed version:

got --help
got init --help

Community

GOT Community is the complete free and open-source foundation of GOT. Bug reports, focused feature proposals, documentation improvements, and code contributions are welcome through the repository's GitHub issues and pull requests.

Support GOT

GOT Community is free and open source. If GOT saves you time or helps your projects, you can support it by:

• Starring the repository.
• Reporting reproducible bugs.
• Suggesting focused improvements.
• Contributing code or documentation.
• Sponsoring the project when an official sponsorship channel is available.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Participation is governed by the Code of Conduct. Please report vulnerabilities according to SECURITY.md.

Security

Do not publish vulnerability details or credentials in public issues. Follow the private reporting guidance in SECURITY.md.

License

Licensed under the Apache License 2.0.