Skip to main content

Usage

Basic Commands​

Create a New Application​

regius new myapp

This creates a new web application with all the necessary files and directories. The scaffold defaults to the templ renderer (github.com/a-h/templ + templui + Tailwind v4) and the sqlite database, and ships a runnable auth scaffold (navbar, sign in/up/forgot/reset-password).

Optional flags:

  • --db <type>: Pre-fill DATABASE_TYPE in the generated .env (postgres|postgresql|mysql|mariadb|sqlite|sqlite3). Defaults to sqlite (a local file at data/<name>.db, no server needed).
  • --renderer <engine>: Template engine to scaffold — templ (default) | jet (github.com/CloudyKit/jet/v6, *.jet views with shared views/layouts/*.jet layouts) | go (built-in html/template, *.page.template views with a shared views/layouts/*.layout.template layout system). regius make auth and regius make handler also accept --renderer, falling back to the RENDERER env var then templ.
  • -v, --verbose: Stream go get / go mod tidy output live instead of capturing it (the captured output is shown only on failure by default).
regius new myapp --db postgres -v
regius new jetapp --renderer jet
regius new goapp --renderer go

After regius new, run the auth migration and start the app:

cd myapp
regius migrate          # creates users/tokens/remember_tokens on sqlite
go run .                # http://localhost:4000  (/ , /auth/signin)

Show Help​

regius help

Displays all available commands and their usage. You can also get help for any specific command or subcommand:

regius make migration --help
regius migrate --help

Check Version​

regius version

Shows the current version of Regius.

Develop with Hot-Reload​

regius dev

Starts your app and watches the project for changes. When you save a Go file, template, or config file, the app is rebuilt and restarted automatically (.templ changes run templ generate first, and a tailwindcss --watch subprocess keeps the stylesheet fresh). If a rebuild fails, the previously started process keeps serving until the next successful build. No external tools required.

Open browser tabs reload automatically after every restart and after CSS-only rebuilds (via the DevReload middleware). Disable with --no-browser-reload.

Optional flags:

  • --port <n>: override the PORT from .env
  • --build-delay <dur>: debounce delay after the last change (default 500ms)
  • --no-tailwind: disable the Tailwind CSS watcher
  • --no-templ: disable automatic templ generate
  • --no-browser-reload: disable automatic browser reload
  • --exit: exit on build failure instead of keeping the old process alive
  • --ignore <paths>: comma-separated extra paths to ignore
  • --watch <paths>: comma-separated extra paths to watch
  • -v, --verbose: stream build output live

See the Browser Live-Reload section for details on the middleware.

Database Migrations​

Run All Pending Migrations​

regius migrate

Runs all pending migrations (defaults to "up").

regius migrate up

Runs all pending migrations explicitly.

Rollback Migrations​

regius migrate down [steps|all]

Reverses migrations. Use a number to reverse a specific number of steps, or all to reverse all migrations.

# Reverse last 2 migrations
regius migrate down 2

# Reverse all migrations
regius migrate down all

Reset Migrations​

regius migrate reset

Runs all "down" migrations in reverse order, then all "up" migrations.

Check Migration Version​

regius migrate version

Shows the current migration version (uses golang-migrate).

Create a Migration​

regius make migration create_users_table

Creates two new migration files (up and down) in the migrations folder.

Use the --format=sql flag to create SQL-format migration files:

regius make migration create_users --format=sql

Seeding​

Create a Seed File​

regius make seed default_users

Creates a new SQL seed file in the seeds/ directory.

Run Seeds​

regius db:seed

Runs all pending seed files in seeds/ (in filename order), tracking executed seeds in the regius_seeds table. Seed files are plain .sql files executed in a single transaction, and each is only applied once.

Code Generation​

Create a Model​

regius make model User

Creates a new model in the data directory with proper pluralization.

Create a GORM Model​

regius make gorm-model User

Creates a new GORM model in the data directory with proper pluralization.

Create a Handler​

regius make handler Home

Creates a stub handler in the handlers directory.

Create Mail Templates​

regius make mail Welcome

Creates two starter mail templates in the mail directory.

Generate Encryption Key​

regius make key

Generates a 32-character encryption key for use in the KEY environment variable.

Create an API Handler​

regius make api User

Creates a CRUD API handler with pagination and a response envelope, mounted in routes-api.go. Pass --with-resource to also generate an API resource (JSON transformer).

Create a Webhook Endpoint​

regius make webhook stripe-payment --provider stripe

Creates a signed inbound webhook endpoint (providers: generic, github, stripe) mounted at /api/webhooks/<name>. See the Webhooks section.

Create a Background Job​

regius make job send-welcome-email

Creates a background job (typed payload, handler, enqueue helper) in the workers directory. See the Background Jobs section.

Create a WebSocket Endpoint​

regius make websocket chat

Creates a WebSocket endpoint mounted at /ws/<name>. See the WebSockets section.

Create a CRUD Slice​

regius make crud Post --renderer templ

Creates a full-stack web CRUD slice: model, migration, resource controller, renderer-aware views, and routes mounted at /<table>s.

Create an API Resource​

regius make resource User

Creates an API resource (resources/<name>_resource.go): a JSON transformer that shapes a model for the {data, error, meta} response envelope.

Create a Middleware​

regius make middleware Auth

Creates a custom middleware stub as a method on the app's Middleware struct. Pass --global to also wire it into the global chain in routes.go.

Create a Service​

regius make service Notifications

Creates a service-layer stub (services/<name>.go) with App/Models injected.

Create a Locale​

regius make locale fr

Creates a new translation locale file. See the Internationalization section.

Authentication​

Generate Authentication Scaffolding​

regius make auth

Creates and runs migrations for authentication tables, and creates models, middleware, handlers, and views.

Session Management​

Create Session Store​

regius make session

Creates a table in the database for session storage.

Maintenance Mode​

Enable Maintenance Mode​

regius down

Puts the server in maintenance mode.

Disable Maintenance Mode​

regius up

Brings the server back from maintenance mode.

Configuration​

All configuration is done through the .env file in your project root. See the Configuration section for details on all available options.

Rendering Templates​

Regius provides a unified render.Template interface that works across all three supported template engines: jet, go, and templ. Every handler calls the same Page() method — the only difference is how the Template is created.

Jet Templates​

func (h *Handlers) Home(w http.ResponseWriter, r *http.Request) {
    err := h.App.Render.Page(w, r, h.App.Render.Jet("home", nil), nil)
    if err != nil {
        h.App.ErrorLog.Println("error rendering", err)
    }
}

Pass jet variables via the second argument:

vars := make(jet.VarMap)
vars.Set("email", "user@example.com")
h.App.Render.Page(w, r, h.App.Render.Jet("reset-password", vars), data)

Go Templates​

err := h.App.Render.Page(w, r, h.App.Render.Go("home"), nil)

Templ Components​

Templ components implement render.Template natively — pass them directly with no wrapper and no registration:

err := h.App.Render.Page(w, r, views.Home(), &render.TemplateData{Data: data})

Mixing Engines​

Each handler independently chooses its engine, so you can mix jet, go, and templ in the same application:

func (h *Handlers) Home(w http.ResponseWriter, r *http.Request) {
    h.App.Render.Page(w, r, views.Home(), data)           // templ
}

func (h *Handlers) Forgot(w http.ResponseWriter, r *http.Request) {
    h.App.Render.Page(w, r, h.App.Render.Jet("forgot", nil), nil)  // jet
}