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

Generated home page	Scaffold CRUD — posts list
Edit form	Post detail view
Registration page (--auth)	Custom 404 page

---

Why Catuaba?

You want	Catuaba gives you
Start a project fast	catuaba new myapp — full app in 3 seconds
CRUD without boilerplate	catuaba g scaffold — model, views, API, routes, migration
Type-safe HTML	Templ — compiled templates, IDE autocomplete, no interface{}
Interactivity without JS frameworks	HTMX + Alpine.js — 31kb total
Production CSS	Tailwind CSS — standalone binary, no Node.js
Auth that just works	--auth — login, register, logout, sessions, bcrypt
AI-powered development	Built-in MCP server — Claude/Cursor understand your project
Deploy anywhere	Single binary + Docker. That's Go.

The Stack

Layer	Technology
HTTP	Gin
ORM	GORM — Postgres, MySQL, SQLite
Views	Templ — type-safe, compiled HTML
Interactivity	HTMX + Alpine.js
CSS	Tailwind CSS
Sessions	SCS
Migrations	Raw SQL (up/down) via golang-migrate

---

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:

What	Where
Model	app/models/post.go
Migration	database/migrations/*_create_posts.{up,down}.sql
HTML handlers	app/controllers/posts/ (index, show, new, create, edit, update, delete)
Templ views	app/views/posts/ (index, show, form)
Routes	Auto-injected into config/routes.go

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:

Method	Path	Description
GET	/products	List with pagination
GET	/products/new	New form
POST	/products	Create
GET	/products/:id	Detail view
GET	/products/:id/edit	Edit form
POST	/products/:id	Update
POST	/products/:id/delete	Delete

JSON API routes:

Method	Path
GET	/api/products
POST	/api/products
GET	/api/products/:id
PUT/PATCH	/api/products/:id
DELETE	/api/products/:id

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

Type	Go	SQL	HTML
string	string	VARCHAR(255)	text input
text	string	TEXT	textarea
integer	int	INTEGER	number input
float	float64	REAL	number input
boolean	bool	BOOLEAN	checkbox
datetime	time.Time	TIMESTAMP	datetime-local

---

Commands

Command	Description
catuaba new <name>	Create application
catuaba g scaffold <name> [fields...]	Full-stack CRUD
catuaba g api <name> [fields...]	JSON API
catuaba g model <name> [fields...]	Model + migration
catuaba g controller <name> [methods...]	Controller
catuaba g middleware <name>	Middleware
catuaba g service <name>	Service
catuaba g seed <name>	Database seed
catuaba g migration <name>	SQL migration
catuaba g view <name>	Templ view page
catuaba server	Start server
catuaba routes	List all routes
catuaba db migrate	Run pending migrations
catuaba db rollback	Rollback last migration
catuaba db status	Migration status
catuaba install <plugin>	Install plugin
catuaba mcp	Start MCP server

---

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:

Topic	Link
HTTP framework	Gin documentation
ORM	GORM documentation
Views	Templ guide
Interactivity	HTMX documentation
Client-side JS	Alpine.js documentation
CSS	Tailwind CSS documentation
Sessions	SCS documentation
Migrations	golang-migrate

---

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:

Middleware	What it does
Health	GET /health returns 200
RequestID	X-Request-ID on every response
Logger	Structured JSON: method, path, status, latency
Recovery	Catches panics → 500
SecureHeaders	HSTS, X-Frame-Options, CSP
CORS	Configurable via CORS_ALLOWED_ORIGIN
RateLimit	Token bucket: 10 req/s, burst 40
Session	SCS cookie sessions
CSRF	Auto token validation (skips /api/ routes)
Flash	Flash messages: success, error, warning

---

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

Driver	Flag	Example
PostgreSQL	--db postgres	Default. Docker Compose included
MySQL	--db mysql	Docker Compose included
SQLite	--db sqlite	Zero config, file-based

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:

Resource	Returns
catuaba://project/overview	Module, Go version, DB, port, plugins, directories
catuaba://project/models	All models with fields, types, tags
catuaba://project/routes	All routes: method, path, handler
catuaba://project/controllers	All controllers and functions
catuaba://project/middleware	All middleware functions
catuaba://project/env	Env var names (no values)

Tools — generate code through the AI:

Tool	What it does
generate_scaffold	Full CRUD: model + handlers + views + API + routes
generate_model	Model + SQL migration
get_model	Inspect model details
get_routes	List routes (filterable by prefix)
get_logs	Recent app logs (filterable by level/path)
run_command	Run any catuaba generate subcommand
install_plugin	Install a plugin

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.