docs

getting started

installation

Installation

This guide installs the Mithril CLI and sets up a new project.

Prerequisites#

Go 1.25+ — Download Go
Git — Download Git
Make — GNU Make (pre-installed on macOS/Linux)
Docker (optional) — for local Postgres and dev services

Install the CLI#

Method 1: Install script (recommended)

curl -fsSL https://raw.githubusercontent.com/mithril-framework/mithril/main/install.sh | sh

This runs GOPROXY=direct go install github.com/mithril-framework/mithril/cmd/mithril@v1.0.2 and verifies the installed binary. The install script bypasses stale proxy.golang.org cache (which may still serve v0.1.0 as @latest).

If an old scaffold CLI is on /usr/local/bin, the script exits with an error until you run sudo $(go env GOPATH)/bin/mithril init or fix PATH — this prevents silently using the wrong binary in a new terminal.

After install, add Go bin to your PATH (required if another mithril exists on the system):

export PATH="$(go env GOPATH)/bin:$PATH"
mithril --version   # expect: mithril 1.0.2 (github.com/mithril-framework/mithril)

Put that export in ~/.zshrc or ~/.bashrc. If mithril --version prints dev, run sudo $(go env GOPATH)/bin/mithril init or fix PATH order.

Method 2: go install

go install github.com/mithril-framework/mithril/cmd/mithril@v1.0.2
mithril --version

Method 3: From source

git clone https://github.com/mithril-framework/mithril.git
cd mithril
go build -o bin/mithril ./cmd/mithril
sudo ln -sf "$(pwd)/bin/mithril" /usr/local/bin/mithril
mithril --version

Create a Project#

mithril new hello-mithril
cd hello-mithril
mithril install

mithril new clones the framework, removes dev cruft (stray binaries), rewrites the Go module (defaults to github.com/your-user/project-name when gh or git config github.user is set), copies env.example → .env, runs go mod tidy, and initializes a fresh git repository on the main branch.

Override the module path:

mithril new -module github.com/acme/api my-api

Start Developing#

# Start PostgreSQL (Docker) — trust auth, database mithril_rev
make dc-up-postgres

# Run migrations
mithril migrate-up

# Create a login user (pick one)
mithril seed              # user@example.com / password
# mithril createsuperuser
# mithril createsuperuser --email admin@example.com --password 'your-password'

# Run server (port 4000)
mithril run

If Postgres is down, the dev server still starts with limited routes (warning in logs). Use APP_ENV=production to require DB.

Visit:

Clone the Framework Repo#

To contribute or run the framework itself:

git clone https://github.com/mithril-framework/mithril.git
cd mithril
make install
cp env.example .env
make dc-up-postgres
make migrate-up
make run

Inside a project, mithril <target> delegates to make (same as ./mithril shell script).

Environment Variables#

Copy env.example to .env:

cp env.example .env

Key variables:

Variable	Description
`PORT`	HTTP port (default `4000`)
`JWT_SECRET`	Required when `APP_ENV=production`
`DATABASE_URL`	PostgreSQL connection string (overrides `DB_*`)
`DB_HOST`	Set for PostgreSQL; comment out to run without DB
`DB_NAME`	Default `mithril_rev` (matches docker-compose)
`ENABLE_REGISTER`	Set `true` to allow `POST /auth/register`
`ENABLE_COMPRESSION`	Enable gzip responses
`ENABLE_HELMET`	Security headers
`CORS_ORIGINS`	Comma-separated allowed origins

Project Structure#

mithril/
├── main.go                 # Entry point
├── routes/                 # Route registration
├── internal/               # Auth, ACL, admin, CRUD
├── database/
│   ├── models/
│   ├── repositories/
│   └── migrations/         # goose SQL
├── cmd/                    # CLI tools
├── pkg/utils/              # Shared utilities
├── public/admin/           # Admin SPA
├── infrastructure/         # Docker, K8s, compose
├── Makefile
└── mithril                 # make wrapper script

Troubleshooting#

mithril: command not found

Add Go bin to PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Database connection failed

Ensure Postgres is running and .env matches docker-compose:

make dc-up-postgres
# Defaults: user postgres, database mithril_rev, trust auth (no password)

Postgres container won't stay running

On a fresh Docker volume, Postgres 16 needs POSTGRES_HOST_AUTH_METHOD=trust or a non-empty password. Reset:

docker volume rm mithril_postgres_data
make dc-up-postgres

Run without a database

Comment out DB_HOST in .env to preview /, /health, and /docs while debugging Postgres.

Go version mismatch

Mithril requires Go 1.25+. Check with go version.

mithril --version shows dev or scaffold output

Ensure the framework CLI from go install github.com/mithril-framework/mithril/cmd/mithril@v1.0.2 is first on PATH. See Quick Start troubleshooting.

migrate-up says "no migrations to run" on a new project

You may be reusing a local Docker volume from an earlier Mithril project (mithril_postgres_data). That is normal — the database is already migrated. Run mithril migrate-status to confirm. For a completely fresh DB: docker volume rm mithril_postgres_data && make dc-up-postgres.

Documentation