CLI Cheatsheet

grit init

Write the framework's hard-rules convention docs to the project root as CLAUDE.md and AGENTS.md (same content — different AI tools look for different filenames). Skips files that already exist unless --force is passed.

grit new

Scaffold a brand-new Grit monorepo with the Go API, Next.js web app, admin panel, shared packages, Docker configs, and all the batteries.

grit generate resource

alias: grit g resource

Generate a complete full-stack CRUD resource: Go model, handler, service, Zod schemas, TypeScript types, React Query hooks, and an admin page — all wired together automatically.

grit generate seeder

alias: grit g seeder

Generate a database seeder for one or more already-generated resources. Writes internal/database/<name>_seeder.go with one editable example record, registers it in seed.go, and runs with grit seed. Pass --faker to fill many rows instead.

grit generate sequence

alias: grit g sequence

Generate atomic sequential numbers for a resource (e.g. INV-202605-0001). Creates a database-backed counter package plus a typed helper so handlers call services.Next<Name>Number(db, t).

grit remove resource

alias: grit rm resource

Delete all generated files for a resource and reverse all marker-based injections (routes, migrations, sidebar entries).

grit add role

Add a new role constant across the entire stack: Go models, TypeScript types, Zod schemas, constants, and admin resource definitions.

grit add web-auth

Add page-protection helpers to apps/web/: a middleware.ts SSR cookie check that redirects to /login, and a ProtectedWebRoute client wrapper. Existing files are left alone unless --force.

grit expose

Scaffold a public-facing Next.js page in apps/web/ that consumes an already-generated resource — reusing its shared Zod schema and React Query hook instead of re-implementing the form or table.

grit start

Start development servers. With no argument, grit start runs every app in the project in parallel (API + frontends, plus the Wails desktop app when present) and stops them all on Ctrl+C. Pass an app name to run just one.

grit sync

Parse Go model files and regenerate TypeScript types and Zod schemas in packages/shared. Run this whenever you manually edit a Go model to keep frontend types in sync.

grit migrate

Connect to the database and run GORM AutoMigrate for all registered models. Use --fresh to drop all tables first for a clean slate.

grit seed

Populate the database with initial data including an admin user and demo records. Perfect for bootstrapping a fresh development environment.

grit backup

Dump every registered model to a ZIP archive: one CSV per table, a dump.sql of INSERTs in parent-to-child order, and a metadata.json manifest. By default the archive is uploaded to object storage; pass --output to write a local file instead.

grit restore

Run migrations, then replay a backup archive's dump.sql inside a single transaction — every row lands or none does. Point it at an empty database; the archive carries data, not schema.

grit studio

Open the GORM Studio database browser at http://localhost:8080/studio. For web projects, make sure your API server is running first.

grit routes

Parse routes.go and print a table of every registered HTTP route with its method, path, handler, and middleware group.

grit upgrade

Upgrade an existing project to the latest scaffold templates. This regenerates framework components (admin panel, web app, configs) while preserving your resource definitions and API code.

grit update

Update the Grit CLI binary to the latest version. It checks GitHub first and exits if you are already up to date. Otherwise, if the Go toolchain is on your PATH it runs go install ...@<latest>; if Go is not installed it downloads the matching prebuilt binary from the GitHub release and atomically swaps it in (on Windows the old .exe is renamed to .old first). Aliased as grit self-update.

grit version

Print the installed Grit CLI version.

grit down / grit up

Toggle maintenance mode. grit down writes a .maintenance file that makes the scaffolded middleware return 503 for every request; grit up removes it and resumes normal handling.

grit deploy

Build the app, upload it over SSH, configure a systemd service, and optionally set up a Caddy reverse proxy with auto-TLS. Flags fall back to DEPLOY_* environment variables.

Desktop apps

Scaffold and ship standalone Wails desktop applications (Go + React + SQLite).

Common Workflows

Copy-paste recipes for everyday development tasks.

# Create the project
$grit new myapp
# Start infrastructure
$cd myapp && docker compose up -d
# Start the API
$grit start server
# In another terminal — start frontend
$grit start client

# Generate the resource
$grit g resource Product --fields "name:string,price:float,description:text,published:bool"
# Sync types to keep everything in sync
$grit sync
# Run migrations to create the table
$grit migrate

# Generate a Category resource first
$grit g resource Category --fields "name:string,description:text"
# Generate Product that belongs to Category
$grit g resource Product --fields "name:string,price:float,category:belongs_to"
# Apply database changes
$grit migrate

# Drop all tables and re-migrate
$grit migrate --fresh
# Re-seed with initial data
$grit seed

# Remove the old resource
$grit rm resource Post --force
# Regenerate with updated fields
$grit g resource Post --fields "title:string,slug:slug,content:richtext,published:bool,views:int"

# Update the CLI first
$grit update
# Then upgrade project templates
$grit upgrade

Full Command Tree

The complete hierarchy of every command and subcommand.

grit
├── init                      # Write CLAUDE.md / AGENTS.md convention docs
│   └── --force               # Overwrite existing files
│
├── new <project-name|.>      # Scaffold a new project
│   ├── --single              # Go API + embedded SPA (one binary)
│   ├── --double              # API + web (no admin)
│   ├── --triple              # API + web + admin (default)
│   ├── --api                 # Go API only
│   ├── --mobile              # API + Expo mobile only
│   ├── --expo                # Add Expo mobile (additive)
│   ├── --desktop             # Add Wails desktop client (combinable, not --single)
│   ├── --full                # Everything + docs site
│   ├── --next / --vite       # Frontend: Next.js or TanStack (Vite)
│   ├── --style <variant>     # Admin style: default, modern, minimal, glass, centered
│   ├── --theme <name>        # Theme: atlas, aurora, pulse
│   ├── --here                # Scaffold into the current directory
│   └── --force               # Allow a non-empty directory
│
├── new-desktop <name>        # Scaffold a standalone Wails desktop app
│
├── generate (g)              # Code generation
│   ├── resource <Name>       # Generate full-stack CRUD resource
│   │   ├── --fields "..."    # Inline field definitions
│   │   ├── --from file.yaml  # YAML field definitions
│   │   ├── -i, --interactive # Interactive field prompts
│   │   ├── --roles "..."     # Restrict routes to roles
│   │   ├── --seed            # Also generate a seeder (one example row)
│   │   ├── --faker           # Also generate a gofakeit seeder (implies --seed)
│   │   └── --count <n>       # Rows for the faker seeder (default 10)
│   ├── seeder <Resource>...  # Seeder for existing resources (--faker, --count)
│   └── sequence <Name>       # Sequential numbering helper (--prefix, --reset, --width)
│
├── remove (rm)               # Remove components
│   └── resource <Name>       # Remove a generated resource
│       └── --force           # Skip confirmation
│
├── add                       # Add components
│   ├── role <ROLE_NAME>      # Add a role across the stack
│   └── web-auth              # Add page-protection helpers to apps/web/ (--force)
│
├── expose                    # Scaffold a web page for a resource
│   ├── form <Resource>       # Public form page (--to, --public-share, --token, --force)
│   └── table <Resource>      # Paginated list page (--to, --force)
│
├── start                     # Development servers (all apps if no arg)
│   ├── server                # Start the Go API (air hot-reload)
│   ├── client                # Start frontend apps (Turborepo)
│   ├── web / admin           # Start a single Next.js app
│   ├── expo                  # Start the Expo mobile app
│   └── desktop               # Start the Wails desktop app
│
├── compile                   # Build desktop app executable (Wails)
├── package                   # Build a distributable desktop installer
│   ├── --platform <os/arch>  # Target platform (default: host)
│   ├── --no-installer        # Raw binary only (skip NSIS on Windows)
│   └── --clean               # Clean the build dir first
│
├── studio                    # Open GORM Studio database browser
├── sync                      # Sync Go types → TypeScript
├── migrate                   # Run database migrations
│   └── --fresh               # Drop all tables first
├── seed                      # Run database seeders
├── backup                    # Back up the entire database
│   └── -o, --output          # Write a local archive instead of uploading
├── restore <backup.zip>      # Restore the database from an archive
│   └── --no-migrate          # Skip migrations before restoring
├── routes                    # List all registered API routes
├── down                      # Enter maintenance mode (503)
├── up                        # Exit maintenance mode
├── deploy                    # Deploy to a remote server
│   ├── --host / --port       # SSH host and port
│   ├── --key                 # SSH private key
│   ├── --domain              # Domain for Caddy + auto-TLS
│   └── --app-port            # Port the app listens on
├── upgrade                   # Upgrade project templates
│   └── -f, --force           # Overwrite without prompting
├── update (self-update)      # Update the CLI binary
│   └── --from-release        # Pull the prebuilt GitHub binary
└── version                   # Print CLI version