Crank

crank is a CLI for creating and maintaining production-ready Go backend services. It scaffolds a layered service, installs selected features, and wraps day-to-day development tools as first-class crank subcommands.

Instead of stitching together routing, configuration, validation, persistence, migrations, Swagger, live reload, and project scripts by hand, you choose the features you need and let crank generate a working project with sensible defaults.

What you can build

A generated crank project gives you:

A Go 1.21 backend service using Echo v4.
A Domain-Driven layout with domain, application, adapter, and composition-root layers.
Configuration through configs/config.yaml, .env, and environment variables.
Structured logging with log/slog.
Request validation with go-playground/validator.
Swagger/OpenAPI generation with swaggo/swag.
Optional PostgreSQL persistence through GORM or Bun.
Optional modules for auth, Redis, MongoDB, Qdrant, Temporal, OpenTelemetry, React views, crypto helpers, and transactional outbox support.
One CLI surface for build, run, test, format, vet, migrations, Swagger, live reload, health checks, and code generation.
Agent-friendly project metadata through .crank.yaml, AGENTS.md, and a project-local Zed skill.

Quick example

# Install crank
curl -fsSL https://raw.githubusercontent.com/anurag925/crank/main/install.sh | sh

# Create a new service with the default ORM, GORM
crank init bookstore --features=base,auth

# Start the service
cd bookstore
cp .env.example .env
crank run

The generated server listens on http://localhost:8080 by default. The health endpoint is available at:

curl http://localhost:8080/health

How the docs are organized

Section	Page	Use it when you want to…
📚 Tutorials	Installation	Install `crank` or build it from source.
	Getting started	Scaffold your first app and run it locally.
📖 Reference	Commands	Learn the full CLI surface.
	Features	Pick the modules to include in a project.
	Generators	Generate models, handlers, scaffolds, workflows, activities, and migrations.
	Configuration	Configure generated applications safely.
	Project structure	Quick reference for where generated code lives.
	Quick reference	Cheat sheet for commands, features, and field types.
🧠 Explanation	Navigating the generated application	Deep dive into the generated code — architecture diagrams, request lifecycle, layer walkthroughs, feature modules, and testing patterns.
	AI agent support	Understand how generated projects guide AI agents to use Crank correctly.
	Feature: Base	Foundation — Echo, Viper, config, validation, logging, in-memory adapters.
	Feature: GORM	PostgreSQL persistence via GORM (default ORM).
	Feature: Bun	PostgreSQL persistence via Bun ORM.
	Feature: Auth	JWT authentication, bcrypt hashing, auth endpoints.
	Feature: Crypto	AES-256-GCM encryption helpers.
	Feature: Redis	Redis caching client and port interface.
	Feature: MongoDB	MongoDB document database client.
	Feature: Qdrant	Qdrant vector database client.
	Feature: Temporal	Temporal workflow orchestration.
	Feature: OpenTelemetry	Distributed tracing with OpenTelemetry.
	Feature: Outbox	Transactional outbox for reliable event delivery.
	Feature: Views	React SPA with Vite, embedded in Go binary.
🔧 How-to Guides	Development workflow	Build, run, test, format, migrate, and generate Swagger docs.
	Recipes	Copy practical workflows for common use cases.
	Troubleshooting	Fix common setup and runtime issues.
	Hosting	Host the documentation site.
	Contributing	Work on `crank` itself.

Core idea

crank separates two concerns:

Project generation — crank init, crank add, and crank make write code into a generated service.
Project operation — commands like crank run, crank test, crank migrate, and crank swag wrap common tools consistently.

That means teams can standardize on a familiar Go project shape while still keeping all generated code ordinary, editable Go.

Recommended next step

Start with Getting started, then read Features before choosing optional modules for a real project.

Last updated: