Catuaba

Build full-stack Go web apps in minutes, not days.
The Rails-like framework that Go developers have been waiting for.

Go is fast, simple, and deploys as a single binary. But starting a web project from scratch means wiring up routers, ORMs, templates, auth, CSRF, sessions, migrations, Docker... hours of boilerplate before you write your first feature.

Catuaba fixes that. One command gives you a production-ready app. Another gives you a full CRUD with views, API, and database — in seconds.

catuaba new blog --db postgres --auth
cd blog
catuaba g scaffold Post title:string content:text published:boolean
make dev

That's it. You now have a running blog with:

• Landing page styled with Tailwind CSS
• Full CRUD for Posts — HTML views and JSON API
• User registration and login with bcrypt + sessions
• Database migrations, CSRF protection, flash messages
• Hot-reload in development (Templ + Tailwind + wgo)
• Docker-ready for production

Why Catuaba?

The Stack

Install

Binary (recommended)

macOS (Apple Silicon)

curl -L https://github.com/dayvsonlima/catuaba/releases/latest/download/catuaba-darwin-arm64.tar.gz | tar xz
sudo mv catuaba /usr/local/bin/

macOS (Intel)

curl -L https://github.com/dayvsonlima/catuaba/releases/latest/download/catuaba-darwin-amd64.tar.gz | tar xz
sudo mv catuaba /usr/local/bin/

Linux

curl -L https://github.com/dayvsonlima/catuaba/releases/latest/download/catuaba-linux-amd64.tar.gz | tar xz
sudo mv catuaba /usr/local/bin/

Windows — download from releases, extract, add to PATH.

From source

go install github.com/dayvsonlima/catuaba@latest

Prerequisites

• Go 1.22+
• Templ — go install github.com/a-h/templ/cmd/templ@latest
• wgo (hot-reload) — go install github.com/bokwoon95/wgo@latest
• A database: PostgreSQL, MySQL, or SQLite

Getting Started

1. Create your app

catuaba new myapp --db postgres
cd myapp
go mod tidy

Flags:

• --db postgres|mysql|sqlite (default: postgres)
• --auth — adds login, register, logout

2. Generate a resource

catuaba g scaffold Post title:string content:text published:boolean

This creates everything:

3. Start developing

make dev

Open http://localhost:8080 — done.

Three watchers run in parallel:

• Templ — recompiles .templ files on save
• Tailwind — rebuilds CSS on save
• wgo — rebuilds and restarts the Go server

Generators

All generators run inside your project directory with catuaba g <generator>.

Full-stack scaffold

catuaba g scaffold Product name:string price:float description:text active:boolean

Creates model + migration + HTML handlers + Templ views + JSON API + routes. This is the fastest way to build features.

HTML routes:

JSON API routes:

API only

catuaba g api Order total:float status:string

Same as scaffold but without HTML views — JSON API only.

Model

catuaba g model Category name:string description:text

Creates model + SQL migration.

Other generators

catuaba g controller Auth login logout           # Controller with methods
catuaba g middleware RateLimit                    # Middleware
catuaba g service EmailSender                    # Service layer
catuaba g seed Posts                             # Database seed
catuaba g migration add_category_id_to_posts     # Empty SQL migration
catuaba g view about                             # Templ page

Field types

Commands

Documentation

For detailed guides on each part of the framework:

• Models — GORM models, field types, relationships, migrations, querying
• Controllers — HTML handlers vs JSON API, form binding, route patterns
• Views — Templ templates, layouts, components, HTMX, Alpine.js, Tailwind CSS
• Middleware — Built-in stack, CSRF, sessions, flash messages, auth, custom middleware

External references:

Project Structure

myapp/
├── application.go              # Entrypoint: middleware stack, routes, graceful shutdown
├── Makefile                    # dev, build, test, docker
├── Dockerfile                  # Multi-stage production build
├── docker-compose.yml          # App + database
├── .env                        # Environment variables
├── config/
│   ├── config.go               # Env vars → AppConfig struct
│   └── routes.go               # Routes (auto-managed by generators)
├── database/
│   ├── connection.go           # GORM connection + migration runner
│   └── migrations/             # SQL files (up/down)
├── app/
│   ├── models/                 # GORM models
│   ├── controllers/
│   │   ├── home.go             # Home page
│   │   ├── {resource}/         # HTML handlers (scaffold)
│   │   └── api/{resource}/     # JSON handlers (api/scaffold)
│   └── views/
│       ├── layouts/base.templ  # HTML5 layout: head, nav, flash, footer
│       ├── components/         # Reusable: nav, flash, pagination, form fields
│       ├── pages/              # Static pages: home, 404
│       └── {resource}/         # CRUD views: index, show, form
├── middleware/                  # Full stack (see below)
└── static/css/                 # Tailwind source + compiled output

Middleware

Every app comes with a production-ready middleware stack — no configuration needed:

Authentication

catuaba new myapp --db postgres --auth

Generates a complete auth system:

• GET /register — registration form
• POST /register — create account
• GET /login — login form
• POST /login — authenticate
• POST /logout — destroy session
• RequireAuth() middleware — protects routes, redirects to /login

Passwords are hashed with bcrypt. Sessions use SCS (cookie-based, OWASP-compliant).

Database

Drivers

Migrations

Raw SQL, versioned, up/down:

# Auto-generated with models and scaffolds
database/migrations/20240101120000_create_posts.up.sql
database/migrations/20240101120000_create_posts.down.sql

# Manual migration
catuaba g migration add_slug_to_posts

# Run / rollback / check
catuaba db migrate
catuaba db rollback
catuaba db status

MCP Server (AI Integration)

Catuaba ships with a built-in MCP server. AI coding assistants (Claude Code, Cursor, Windsurf) can understand your project structure and generate code — without reading every file.

Setup

Every generated app includes a .mcp.json file — just open the project in Claude Code or Cursor and the MCP server is auto-discovered.

For manual setup, add to your .mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "catuaba": {
      "command": "catuaba",
      "args": ["mcp"]
    }
  }
}

What the AI gets

Resources — your project as compact JSON:

Tools — generate code through the AI:

Every generated app also includes a CLAUDE.md with framework conventions, so AI assistants follow the right patterns automatically.

Plugins

Extend Catuaba with plugins:

catuaba install stripe-payments             # From registry
catuaba install https://github.com/user/my-plugin  # From git
catuaba install ./local-plugin              # From local path

catuaba plugin list                         # Browse registry
catuaba plugin info stripe-payments         # Details

Plugins are defined by a plugin.yaml manifest and can add files, inject routes, add imports, insert struct fields, and set environment variables.

Deploy

Docker (recommended)

docker compose up -d --build

The generated Dockerfile is a multi-stage build:

1. Installs Templ + builds templates
2. Builds Tailwind CSS (minified)
3. Compiles Go binary with -ldflags="-w -s"
4. Runs on alpine:3.19 (~15MB image)

Manual

make build
./bin/myapp

Development

Make targets

make dev          # Hot-reload (templ + tailwind + wgo)
make build        # Production binary
make test         # go test ./...
make tidy         # go mod tidy
make docker-up    # Docker Compose up
make docker-down  # Docker Compose down

Contributing

Contributions are welcome!

git clone https://github.com/dayvsonlima/catuaba.git
cd catuaba
go mod tidy
go test -v ./...

1. Fork the repo
2. Create your branch (git checkout -b feature/my-feature)
3. Run tests (go test ./...)
4. Submit a PR

License

MIT License — see LICENSE for details.