The gofasta binary — the command-line tool for Gofasta, a Go backend toolkit. It creates new projects, generates code, runs the development loop (gofasta dev), and ships first-class agent integration. It is a standalone Go binary that does not import the gofasta library at runtime — it only manipulates files on disk.
Gofasta is split across three independent repositories. Each has its own release cycle and go.mod / package.json.
| Repo | Role |
|---|---|
gofastadev/cli |
You are here. The gofasta binary — gofasta new, code generation, and the dev loop. |
gofastadev/gofasta |
The library your project imports — every package under pkg/*. |
gofastadev/website |
The docs site at gofasta.dev. |
For full documentation — every command's flags, every package's API, every guide — visit gofasta.dev. This README covers CLI installation, scaffolding, and the most common workflows; everything else is on the website.
The CLI lives in its own Go module (github.com/gofastadev/cli) with main.go at cmd/gofasta/. It is not the same as the github.com/gofastadev/gofasta library, which your generated projects import as a dependency. You install one, you import the other.
Option A — go install (recommended for Go developers, requires Go 1.25.0+, install Go: https://go.dev/doc/install):
go install github.com/gofastadev/cli/cmd/gofasta@latestCompiles the CLI from source using your local Go toolchain and drops the gofasta binary into $GOBIN (or $GOPATH/bin if GOBIN is unset — usually ~/go/bin).
Option B — Pre-built binary via shell script (no Go toolchain needed):
curl -fsSL https://raw.githubusercontent.com/gofastadev/cli/main/dist/install.sh | shDownloads the latest pre-built binary for your platform from GitHub Releases and installs it to /usr/local/bin/gofasta. Works on macOS and Linux for both amd64 and arm64. The script detects your shell and prints exact export PATH=… instructions if the install directory isn't already on your $PATH.
Verify the installation:
gofasta --helpThis is the single most common first-time issue with any go install-distributed CLI, not specific to gofasta. Go installed the binary into $GOPATH/bin (typically ~/go/bin), but that directory isn't on your shell's $PATH.
Verify the binary is actually there:
ls -l "$(go env GOPATH)/bin/gofasta"If you see the binary, the install worked — you just need to make the directory reachable. Add one line to your shell config and reload:
# zsh (default on macOS)
echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.zshrc
source ~/.zshrc
# bash
echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc
source ~/.bashrc
# fish
fish_add_path (go env GOPATH)/binAfter that, gofasta --help should work in any new terminal session. This is a one-time setup — every future go install lands in the same directory.
Earlier releases of the CLI shipped with a hardcoded Version = "dev" default that only got overridden for pre-built binaries. go install never applies build-time flags, so installs via Option A always reported dev regardless of the actual version. This was fixed in v0.1.3: the CLI now reads the installed module version via runtime/debug.ReadBuildInfo() at startup, so go install users see the correct tag.
If you installed before v0.1.3, re-run go install github.com/gofastadev/cli/cmd/gofasta@latest to pick up the fix.
| You have Go installed | You don't have Go installed |
|---|---|
Option A — go install compiles a native binary with your exact toolchain and there's nothing to keep in sync. Upgrade with go install …@latest. |
Option B — shell script. Downloads a pre-built binary from GitHub Releases. Upgrade with gofasta upgrade. |
Both end up as a gofasta binary in a standard directory. Use whichever matches your environment.
gofasta new myappOr with a full module path:
gofasta new github.com/myorg/myappThis creates a complete, ready-to-run project:
myapp/
├── app/ # Your application code
│ ├── main/main.go # Entry point
│ ├── models/ # Database models (User starter included)
│ ├── dtos/ # Request/response types
│ ├── repositories/ # Data access layer
│ ├── services/ # Business logic
│ ├── rest/
│ │ ├── controllers/ # HTTP handlers
│ │ └── routes/ # Route definitions
│ ├── graphql/
│ │ ├── schema/ # GraphQL schema files (.gql)
│ │ └── resolvers/ # GraphQL resolvers
│ ├── validators/ # Input validation rules
│ ├── di/ # Dependency injection (Google Wire)
│ └── jobs/ # Cron jobs
├── cmd/ # CLI commands for your app
│ ├── root.go # Cobra root command
│ ├── serve.go # Starts the HTTP server
│ └── seed.go # Runs database seeders
├── db/
│ ├── migrations/ # SQL migration files
│ └── seeds/ # Database seed functions
├── configs/ # RBAC policies, feature flags
├── deployments/ # Docker, Kubernetes, CI/CD, nginx, systemd
├── templates/emails/ # HTML email templates
├── locales/ # Translation files
├── config.yaml # Application configuration
├── compose.yaml # Docker Compose (app + PostgreSQL)
├── Dockerfile # Production container image
├── Makefile # Development shortcuts
└── gqlgen.yml # GraphQL code generation config
The project imports github.com/gofastadev/gofasta as a library dependency. It does not contain any CLI or gofasta library internals — only your application code.
- Creates the project directory
- Runs
go mod initwith your module path - Copies ~78 template files, replacing placeholders with your project name
- Runs
go get github.com/gofastadev/gofasta@latestto pull the gofasta library as a project dependency, plus tool dependencies. The tool deps are recorded asgo.modtools (Go 1.24+) and fetched on firstgo mod tidy— no separate install required by the user. They are: Wire (DI codegen), gqlgen (GraphQL codegen), Air (hot reload), and swag (Swagger generator). - Runs
go mod tidy - Generates Wire dependency injection code
- Generates GraphQL resolver code
- Initializes a git repository with an initial commit
After creating a project, you have two ways to run it. Either path requires Docker (install: https://docs.docker.com/get-docker/) — the recommended path runs the entire stack in containers; the host-machine path uses Docker only for PostgreSQL and runs the app on the host.
cd myapp
# Option 1: Docker (recommended — starts app + PostgreSQL)
make up
# Option 2: Host machine (requires local PostgreSQL or Docker for the DB)
docker compose up db -d # Start just the database
make dev # Run with hot reload (uses Air, fetched as a go.mod tool)Your app is now running:
- REST API:
http://localhost:8080/api/v1/ - GraphQL:
http://localhost:8080/graphql - GraphQL Playground:
http://localhost:8080/graphql-playground - Health check:
http://localhost:8080/health
The generate command (shorthand: g) creates boilerplate code for new resources. Every generated file is auto-wired into the dependency injection container, routes, and GraphQL schema.
gofasta g scaffold Product name:string price:floatThis single command creates 11 files and patches 4 existing files:
| Created file | What it is |
|---|---|
app/models/product.model.go |
Database model with name and price fields |
db/migrations/000006_create_products.up.sql |
SQL to create the products table |
db/migrations/000006_create_products.down.sql |
SQL to drop the products table |
app/repositories/interfaces/product_repository.go |
Repository interface (contract) |
app/repositories/product.repository.go |
Repository implementation (GORM queries) |
app/services/interfaces/product_service.go |
Service interface (contract) |
app/services/product.service.go |
Service implementation (business logic) |
app/dtos/product.dtos.go |
Request/response DTOs with validation tags |
app/di/providers/product.go |
Wire dependency injection provider |
app/rest/controllers/product.controller.go |
REST controller with CRUD handlers |
app/rest/routes/product.routes.go |
Route definitions (GET, POST, PUT, DELETE) |
It also patches these files automatically:
app/di/container.go— addsProductServiceandProductControllerfieldsapp/di/wire.go— addsProductSetto the Wire buildapp/rest/routes/index.routes.go— registers Product routescmd/serve.go— wiresProductControllerinto the route config
After scaffolding, run migrations and start coding your business logic:
gofasta migrate up
# Edit app/services/product.service.go — that's where your logic goesgofasta g scaffold Product name:string price:float --graphqlThe --graphql flag additionally creates a .gql schema file and auto-wires a GraphQL resolver.
| Type | Go type | SQL type (Postgres) | GraphQL type |
|---|---|---|---|
string |
string |
VARCHAR(255) |
String |
text |
string |
TEXT |
String |
int |
int |
INTEGER |
Int |
float |
float64 |
DECIMAL(10,2) |
Float |
bool |
bool |
BOOLEAN |
Boolean |
uuid |
uuid.UUID |
UUID |
ID |
time |
time.Time |
TIMESTAMP |
DateTime |
SQL types are automatically adapted for MySQL, SQLite, SQL Server, and ClickHouse based on the database.driver in your config.yaml.
You don't have to scaffold everything at once. Generate only what you need:
# Just the model + migration
gofasta g model Product name:string price:float
# Model + repository
gofasta g repository Product name:string price:float
# Model + repo + service + DTOs + Wire provider
gofasta g service Product name:string price:float
# Everything up to controller + routes
gofasta g controller Product name:string price:float
# Individual pieces
gofasta g dto Product name:string price:float # DTOs only
gofasta g migration Product name:string # SQL files only
gofasta g route Product # Route file only
gofasta g provider Product # Wire provider only
gofasta g resolver Product # Patch GraphQL resolver# Cron job (runs on a schedule)
gofasta g job cleanup-tokens "0 0 0 * * *" # Daily at midnight
gofasta g job send-reports "0 0 9 * * 1" # Every Monday at 9am
gofasta g job sync-data # Defaults to every hour
# Async task (enqueued and processed in background)
gofasta g task send-welcome-email
gofasta g task process-paymentgofasta g email-template order-confirmation
# Creates templates/emails/order-confirmation.htmlPer-command reference. Every
gofastacommand has a dedicated page on gofasta.dev/docs/cli-reference with all its flags, error codes, and recipes. The README below is a tour of the most common workflows; the website is the source of truth for flag-level detail.
gofasta migrate up # Apply all pending migrations
gofasta migrate down # Rollback the last migrationgofasta seed # Run all seed functions
gofasta seed --fresh # Drop all tables, re-migrate, then seedRun this once after cloning an existing gofasta project:
gofasta initThis creates .env from .env.example, runs go mod tidy, generates Wire and GraphQL code, runs migrations, and verifies the build.
gofasta swaggerGenerates OpenAPI/Swagger docs from code annotations.
gofasta wireRegenerates the Wire dependency injection code after manual changes to providers.
Gofasta ships first-class integration with AI coding agents. Every command below honors the global --json flag for machine-parseable output, and every error carries a stable code + remediation hint + docs link.
Runs the full preflight gauntlet (gofmt, vet, golangci-lint, tests with the race detector, build, Wire drift, routes) in one command. Fails fast on the first failing step; pass --keep-going to report every result.
gofasta verify # human table
gofasta verify --json # structured per-check JSON
gofasta verify --no-lint # skip golangci-lint on machines that don't have itReports whether derived artifacts (Wire, Swagger), generated files, and module state are in sync with their inputs. Complementary to verify — verify is about quality gates; status is about drift.
gofasta status # text table
gofasta status --json # one JSON object per checkAST-parses a resource's model, DTOs, service interface, controller, and routes; emits a single structured report. Replaces opening six files by hand.
gofasta inspect User
gofasta inspect User --json | jq '.service_methods[].name'Emits a Draft-7 JSON Schema describing config.yaml. Feed it to VS Code / JetBrains YAML extensions for autocomplete and inline validation, or to CI for pre-deploy checks. Shells out to a project-local cmd/schema helper so the schema always matches the gofasta version pinned in your go.mod.
gofasta config schema > config.schema.json
# Then, at the top of config.yaml:
# # yaml-language-server: $schema=./config.schema.jsonPre-defined sequences of gofasta commands that together accomplish one higher-level task. Transparent (no hidden logic, each step is a command you could run by hand) but save agent round-trips and keystrokes:
gofasta do new-rest-endpoint Invoice total:float # scaffold + migrate up + swagger
gofasta do rebuild # wire + swagger
gofasta do fresh-start # init + migrate up + seed
gofasta do clean-slate # db reset + seed
gofasta do health-check # verify + status
gofasta do list # every supported workflowPass --dry-run to preview the chain.
A brand-new gofasta new project ships zero agent-related files. Agent setup is fully opt-in, per agent. Running gofasta ai <key> installs a self-contained tree at the locations that agent reads natively — no rename of pre-existing files, every file lands at its final path on first install and is removed wholesale on uninstall.
gofasta ai claude # CLAUDE.md + .claude/{settings,hooks,commands,rules}/
gofasta ai cursor # .cursor/rules/*.mdc (6 topic rules, no root briefing)
gofasta ai codex # AGENTS.md + .codex/{config.toml, docs/*.md}
gofasta ai aider # CONVENTIONS.md + .aider.conf.yml + .aider/docs/*.md
gofasta ai windsurf # .windsurf/rules/*.md (6 topic rules, no root briefing)
gofasta ai list # supported agents
gofasta ai status # what's currently installed in this projectEvery install ships a slim root briefing (where the agent expects one) plus six topic chunks — conventions, overview, workflow, commands, debugging, docs-index — wrapped with the right activation metadata for that agent (Claude's paths:, Cursor's alwaysApply / globs / description, Windsurf's trigger:, etc.). Each chunk stays under the agent's per-file size cap (Claude 200-line target, Codex 32 KiB, Windsurf 12 KB).
Installs are idempotent, support --dry-run, and are tracked in .gofasta/ai.json. Only one agent can be active at a time — pass --switch to atomically uninstall the previous one and install the new one.
Every command that emits structured output honors the global --json flag, producing a single-line JSON document suitable for agent parsing, jq filtering, or CI consumption.
gofasta routes --json | jq '.[] | select(.method == "POST")'
gofasta --json verify | jq '.checks[] | select(.status == "fail")'
gofasta ai list --jsonEvery CLI error carries {code, message, hint, docs} — agents pattern-match on the stable code and read the hint for the remediation. No regex-parsing English error strings.
$ gofasta --json g scaffold 2>&1 >/dev/null | jq .
{
"code": "INVALID_NAME",
"message": "missing resource name",
"hint": "pass a PascalCase resource name — e.g. `gofasta g scaffold Product`",
"docs": "https://gofasta.dev/docs/cli-reference/generate/scaffold"
}The CLI is a standalone Go binary. It does not import the gofasta library — it only manipulates files on disk.
-
gofasta newuses Go'sembed.FSto carry project template files inside the binary. Templates are rendered withtext/template, replacing{{.ModulePath}}with your project's module path and{{.ProjectNameLower}}with your project name. -
gofasta g scaffoldreads Go template strings (for models, services, controllers, etc.) and renders them with your resource name and field definitions. It then patches existing files (container, wire, routes, serve) by finding insertion points via string matching. -
gofasta dev,gofasta migrate,gofasta initare thin wrappers that shell out to external tools (air,migrate,go mod tidy). They read yourconfig.yamlto get database connection details. -
gofasta serveandgofasta seeddelegate to your project's own binary (go run ./app/main serve) because they need to import your project's code.
cli/
├── cmd/gofasta/main.go # CLI entry point
├── internal/
│ ├── commands/ # Cobra command definitions
│ │ ├── root.go # Root command + subcommand registration
│ │ ├── new.go # Project scaffolding
│ │ ├── dev.go # Development server
│ │ ├── init_cmd.go # Project initialization
│ │ ├── migrate.go # Database migrations
│ │ ├── serve.go # Passthrough to project serve
│ │ ├── seed.go # Passthrough to project seed
│ │ ├── swagger.go # Swagger generation
│ │ └── configutil/ # Reads config.yaml without importing the gofasta library
│ ├── generate/ # Code generation engine
│ │ ├── commands.go # Generate subcommands and step chains
│ │ ├── types.go # ScaffoldData, Field, Step types
│ │ ├── scaffold_data.go # Builds template data from CLI args
│ │ ├── writer.go # Renders templates to files
│ │ ├── patcher.go # Patches existing files (adds imports, fields)
│ │ ├── runner.go # Runs Wire and gqlgen after generation
│ │ ├── fieldparse.go # Parses "name:string" field definitions
│ │ ├── stringutil.go # Case conversion, pluralization
│ │ ├── gen_*.go # Individual generators (model, service, etc.)
│ │ └── templates/ # Go template strings for generated code
│ └── skeleton/ # Embedded project templates
│ ├── embed.go # //go:embed all:project
│ └── project/ # ~78 files that become a new project
├── dist/ # CLI distribution files
│ └── install.sh # curl-pipe-sh installer
├── go.mod
└── README.md
Gofasta is currently maintained by one person; sustainability planning — release cadence, security SLOs, the solo-to-team transition, and the automation arc that retires manual steps as the project matures — is documented in the release coordination repo, specifically in CADENCE.md, RELEASING.md, and COMMUNITY.md. Read those three together for the full picture.
Contributions are welcome — see CONTRIBUTING.md.
MIT