Get started · v0.96.0

From cold machine to a running app in four minutes.

Install the CLI, scaffold an app, declare an entity, run it. Every command in this guide is real. Paste it into a terminal and it works.

Prereqs
Go 1.27.3+, git
OS
macOS, Linux, Windows (WSL)
Storage
SQLite by default, Postgres opt-in
Time
~4 minutes

Install

One binary covers scaffold, migrate, dev, build, test, and the doc browser. Get it from GitHub:

$ install
$ go install github.com/DonaldMurillo/gofastr/cmd/gofastr@v0.96.0 $ gofastr --version gofastr v0.96.0

If gofastr isn't found

Make sure $GOPATH/bin (or ~/go/bin) is in your PATH. Run echo $PATH and add the missing entry to your shell rc.

Scaffold

Scaffold a new project. It writes main.go, a sample posts entity in entities/entities.go, a home screen in screens.go at the root, sign-in screens in screens_auth.go, a versioned migration, DESIGN.md, gofastr.settings.yml, and the agent onboarding files (AGENTS.md + .agents/, CLAUDE.md), then initializes git.

$ scaffold
$ gofastr init blog ✓ Created project blog in ./blog/: main.go, screens.go, screens_auth.go, entities/entities.go, gofastr.settings.yml, DESIGN.md, CLAUDE.md, AGENTS.md → next: cd blog && go mod tidy && gofastr dev

Open the scaffolded main.go. It's short, it's yours, and every registration in it is plain Go. Read it.

First entity

The scaffold already declared one. Open entities/entities.go. One declaration is the table, REST CRUD, validation, an OpenAPI spec, and a typed query builder:

blog/entities/entities.go
8 lines
app.Entity("posts", entity.EntityConfig{
  Fields: []schema.Field{
    {Name: "title", Type: schema.String, Required: true},
    {Name: "body", Type: schema.Text},
    {Name: "published", Type: schema.Bool},
  },
  Exposure: &entity.ExposureConfig{CRUD: boolPtr(true)},
})

The matching versioned migration is next to it in the same file. gofastr docs migrations covers how those run.

Run it

Resolve dependencies once, then start the dev server. It rebuilds on save, reloads the browser, and hands your coding agent the app over MCP.

$ run
$ go mod tidy $ gofastr dev → Watching . for changes (.go, .js, .css, .html, .md)... → blog server ready: http://localhost:8080

Open localhost:8080. The scaffolded home screen renders. Then hit the API from a second terminal:

$ probe
$ curl -s http://localhost:8080/api/posts {"error":"authentication required","success":false,…} # 401

That 401 is the point: auto-CRUD refuses anonymous requests unless you opt out. Add Public: true to the entity, save, and the dev server rebuilds. The same curl now answers {"data":[]}. Or keep the gate and sign in: the scaffold already wires the auth battery, so create an account at /register, sign in at /login, and the browser session reaches the same route (gofastr docs auth).

First page

Add a second server-rendered page. A screen is a Go struct whose Render returns the markup. The scaffolded home screen in screens.go is the pattern:

blog/about.go
6 lines
type AboutScreen struct{}

func (s *AboutScreen) ScreenTitle() string { return "About" }
func (s *AboutScreen) Render() render.HTML {
  return ui.PageHeader(ui.PageHeaderConfig{Title: "About"})
}

Register it in main.go next to the home screen: site.Register("/about", &AboutScreen{}, nil). Save, and the dev server serves it.

Tip

Run `gofastr docs` to browse all embedded docs offline, including entity-declarations, query-dsl, and hooks.

What you have

Four minutes in, this is on disk and running:

Running, on disk, yours

  • A server-rendered home screen (plus yours from step 5)
  • A posts entity: REST CRUD at /api/posts, session-gated by default
  • Sign-in screens at /login and /register, backed by the auth battery
  • A versioned SQL migration, already applied
  • An OpenAPI 3 spec (auth-gated; Swagger UI at /api/docs/)
  • MCP under gofastr dev: posts_list/posts_create plus app_routes, and the framework docs through framework_docs_search (the generated main.go registers them), so your coding agent reads the running app
  • AGENTS.md + .agents/ + DESIGN.md, generated for the agent you build with

Where next