andurel

Andurel - Rails-like Web Framework for Go

Andurel is a comprehensive web development framework for Go. It prioritizes development speed. Inspired by Ruby on Rails, it uses just enough conventions to let you build full-stack web applications incredibly fast.

Join the discord here

Platform Support

Andurel v1 supports Linux and macOS on amd64 and arm64. Windows is not supported. Official releases contain and smoke-test all four operating-system and architecture combinations.

See release verification for archive installation, checksums, SBOMs, keyless signatures, and provenance. Maintainers must follow the release procedure before creating a version tag.

The frozen v1 contracts are documented in the public Go API policy, CLI and structured-output policy, and lock schema 1 specification. Model generation supports the conservative SQL subset in the DDL parser contract, and upgrades follow the generated-file ownership policy.

If you'd like to help bring Windows support to Andurel, please see issue #382 - contributions are welcome!

Why Andurel?

Development speed is everything. Andurel eliminates boilerplate and lets you focus on building features:

• Instant Scaffolding - Generate complete CRUD resources with one command
• Live Reload - Hot reloading for Go, templates, and CSS with andurel run powered by Shadowfax
• Type Safety Everywhere - Bun for SQL, Templ/Vue for HTML, Go for logic
• Batteries Included — Echo, Datastar, background jobs, sessions, CSRF protection, telemetry, email support, authentication, optional extensions (docker, aws-ses, css-components)
• Dependency Injection — Declarative application wiring with go.uber.org/fx
• Two Frontend Options — Server-rendered HTML with Templ + Datastar for hypermedia interactivity, or Inertia SPA with Vue 3 or React + Vite for a reactive single-page app
• Production Build — One command (andurel build) to compile everything: Templ, Tailwind CSS, Vite assets, and Go binary
• Just enough Convention - Convention over configuration is great to a certain point. Andurel provides just enough sensible defaults that just work and get out of your way.
• PostgreSQL-Backed - Built on PostgreSQL with River job queues, pgx driver, and UUID support

The core philosophy around resource generation in andurel, is that it should be a one-time operation that creates everything you need for a fully functional CRUD interface. After that, you can modify and extend the generated code as needed but it's yours to manage going forward.

Core Technologies

• Echo - High-performance HTTP framework
• Tailwind CSS - Utility-first CSS tooling
• Bun - Type-safe SQL ORM and query builder
• Templ - Type-safe HTML templates
• Datastar - Hypermedia-driven frontend interactivity
• River - PostgreSQL-backed background jobs and workflows
• OpenTelemetry - Built-in observability
• PostgreSQL - Powerful open-source database with pgx driver and native UUID support
• Shadowfax - Andurel-specific app runner
• go.uber.org/fx - Dependency injection framework
• gonertia - Inertia.js Go adapter (optional, --inertia vue or --inertia react; append /npm, /pnpm, /bun, or /yarn to set JS runtime)
• Vue.js / React - JavaScript UI adapters (optional, via Inertia)
• Vite - Next-generation frontend build tool (optional, via Inertia)

Quick Start

Installation

go install github.com/mbvlabs/andurel@latest andurel --version

For reproducible automation, prefer an explicit stable v1 tag. Projects created with v1.0.0-rc.2 or v1.0.0-rc.3 require manual reconciliation rather than andurel upgrade; follow the RC-to-v1 manual upgrade guide.

Create Your First Project

Andurel gives you choices when creating a new project:

# Create a new project (PostgreSQL + Tailwind CSS)
andurel new myapp # Add extensions for additional features:
andurel new myapp -e docker # Add Dockerfile for containerization
andurel new myapp -e aws-ses # Add AWS SES email integration # Choose your frontend approach:
andurel new myapp --inertia vue # Inertia SPA with Vue 3 + Vite (JS runtime: npm)
andurel new myapp --inertia react/pnpm # Inertia SPA with React + Vite (JS runtime: pnpm)
andurel new myapp --inertia vue/bun # Inertia SPA with Vue 3 + Vite (JS runtime: bun) # Combine options:
andurel new myapp --inertia vue -e docker cd myapp # Sync tools
andurel tool sync # Configure environment
cp .env.example .env # Note: you need to edit .env with your database details # Install JS dependencies (only if using --inertia vue/react)
# andurel new prints the correct package manager command based on the configured runtime (npm/pnpm/bun/yarn) # Apply database migrations
andurel database migrate up # Run the development server (with live reload)
andurel run

Your app is now running on http://localhost:8080

Database Lifecycle Commands

Andurel provides commands to manage your database lifecycle:

# Create the configured database
andurel database create # Requires .env to be filled out with DB credentials # Drop the configured database (prompts for confirmation)
andurel database drop
andurel database drop --force # Allow dropping system databases # Drop and recreate the database
andurel database nuke
andurel database nuke --force # Allow nuking system databases # Full rebuild: drop, recreate, migrate, and seed
andurel database rebuild
andurel database rebuild --force # Allow rebuilding system databases
andurel database rebuild --skip-seed # Skip seeding after migrations

Generate Your First Resource

# Create a migration and add the columns you need. Resource generation requires
# an `id` primary key (uuid/serial/bigserial/string-supported types). `created_at`
# and `updated_at` are optional but recommended.
andurel database migrate new create_products_table # Create a complete resource with model, controller, views, and routes
andurel generate scaffold Product

This single command creates everything you need for a full CRUD interface: model, factory, controller, Templ views, and resource routes. Pass --inertia when you want the generated resource/controller views as Inertia pages instead (reads the adapter from andurel.lock).

Agent-Ready CLI

Andurel's CLI is designed to be consumed by people and agents. Commands that support structured output use a stable response envelope:

{ "ok": true, "data": {}, "summary": "Generated resource", "breadcrumbs": [{"cmd": "andurel routes --json", "description": "Inspect generated routes"}]
}

Structured errors use the same contract:

{ "ok": false, "code": "generation_failed", "error": "failed to generate resource", "hint": "Inspect the error details and generated files, then retry.", "exit_code": 5
}

Output modes

Flag	Purpose
--json	Emit the full {ok,data,summary,breadcrumbs} envelope
--agent	Emit structured output for agents and suppress non-essential human progress output
--md	Emit Markdown where supported
--quiet	Suppress non-essential human output
--jq '.field.path'	Select from the command data payload and emit the selected JSON value directly
--ids-only	Emit only resource identifiers where supported
--count	Emit only resource counts where supported
--verbose	Emit additional diagnostics where supported

Discovery and project inspection

Agents should start with CLI discovery instead of scraping prose:

andurel --agent --help
andurel commands --json
andurel project info --json
andurel config show --json

Project-shape commands are read-only and return structured data:

andurel routes --json
andurel models --json
andurel migrations --json
andurel controllers --json
andurel views --json
andurel jobs --json

The embedded agent skill is available from the binary:

andurel skill show
andurel skill show --json
andurel skill install

skill install writes the Andurel skill into the current project at .codex/skills/andurel/, including the framework-specific layer-placement reference.

Mutation previews

Mutating commands that support --dry-run report artifact changes before writing files:

andurel new myapp --dry-run --json
andurel generate scaffold Product --dry-run --json
andurel generate controller Dashboard overview --dry-run --json
andurel extension add docker --dry-run --json
andurel upgrade --dry-run --json

Add --diff with structured output when you need a text diff preview. Structured mutation reports include created, updated, and deleted files, route additions, commands run, warnings, and breadcrumbs.

CLI Commands

andurel new — Create a new project

Scaffolds a complete Andurel project with the given name.

andurel new (alias: n) [project-name] [flags]

Flag	Description
-e, --extensions	Comma-separated extensions to enable (e.g. docker,aws-ses,css-components)
--inertia	Frontend adapter: vue or react. Optionally append /npm, /pnpm, /bun, or /yarn to set JS runtime (default: npm). Example: --inertia vue/pnpm

andurel generate — Code generation

Generate models, controllers, and scaffolds from your existing database migrations.

andurel generate (alias: g) model NAME [flags]
andurel generate factory NAME [flags]
andurel generate factories [flags]
andurel generate view (alias: v)
andurel generate controller (alias: c) NAME [action ...] [flags]
andurel generate scaffold (alias: s) NAME [flags]
andurel generate job (alias: j) NAME [flags]
andurel generate email (alias: e) NAME
andurel generate routes

generate model — Creates a model from a database migration, or updates an existing one. Fields, types, and timestamps are read from the migration automatically. When --update is applied, Andurel also syncs the matching factory unless --skip-factory is passed.

Flag	Description
--skip-factory	Skip generating or updating the matching factory file
--table-name	Override the default table name (e.g. --table-name=people_data)
--update	Update an existing model from migration changes
--yes	Apply changes without prompting for confirmation (use with --update)
--primary-key	Specify the primary key column (skips interactive detection)
--dry-run	Preview file changes without applying them
--diff	Include a text diff preview in structured output

generate factory — Generates or syncs one model factory from the model entity. With no flags, the singular command syncs by default. Use --check --json in CI or agent workflows to detect drift without writing files, and --sync --json to update the factory.

generate factories — Checks or syncs every model factory in the project. The plural command requires --check or --sync to avoid accidental repo-wide writes. Use --check --json for a structured drift report across all models.

Factory sync treats generated factory declarations as owned by Andurel. In practice, Build<Name>, Create<Name>, Create<Name>s, the factory types, and generated WithX option functions are regenerated from the current model entity. Custom helpers are preserved when they use names that do not collide with those generated declarations.

generate controller — Creates a controller for a resource. With no actions, it generates the full standard CRUD controller, views, and routes. With one or more standard CRUD actions (index, show, new, create, edit, update, destroy), it generates only those resource actions; partial CRUD views are self-contained and only link to companion actions that are also present. Generated resource/controller views default to Templ in every project; pass --inertia to generate Inertia pages (uses the adapter from andurel.lock).

Non-CRUD actions create standalone/custom controller actions. They add empty controller methods, matching Templ components by default or Inertia pages with --inertia, and conventional GET routes:

andurel generate controller Dashboard overview

Generates: