Commands

Complete reference for all Velocity CLI commands.

Global Commands (velocity)

These commands are available globally after installing via Homebrew.

velocity new

Create a new Velocity project with full scaffolding.

velocity new <project-name> [flags]

Arguments:

• project-name - Name of the project directory to create

Flags:

Examples:

# Create a basic project (SQLite by default)
velocity new myapp

# Create with PostgreSQL and Redis
velocity new myapp --database postgres --cache redis

# Create an API-only project
velocity new myapi --api

# API project with PostgreSQL
velocity new myapi --api --database postgres

After creation, the CLI:

1. Scaffolds the project
2. Installs Go dependencies (and JS dependencies for full-stack projects)
3. Runs database migrations
4. Builds the ./vel binary
5. Starts development servers (Go on :4000, Vite on :5173 for full-stack)

API-Only Projects

Use the --api flag to create a lightweight API server without frontend dependencies:

velocity new myapi --api

What’s different:

• No Vite, Tailwind, or React
• No CSRF protection (stateless API)
• JSON-only responses
• API-focused middleware (returns 401 JSON instead of redirects)
• Uses AUTH_GUARD=api by default

Template endpoints:

Project structure:

myapi/
├── routes/api.go           # API route definitions
├── internal/handlers/      # JSON handlers
├── internal/middleware/    # API middleware (auth returns JSON 401)
└── internal/models/        # Database models

velocity config

Manage CLI configuration. See Configuration for details.

velocity config set <key> <value>
velocity config get <key>
velocity config list
velocity config reset

velocity self-update

Update the velocity installer to the latest version.

velocity self-update

Project Commands (vel)

These commands run from within a Velocity project using ./vel or vel (with shell function).

vel serve

Start the development server with hot reload.

vel serve [flags]

Flags:

Examples:

# Start with defaults (port 4000, hot reload enabled)
vel serve

# Custom port
vel serve --port 3000

# Production environment, no hot reload
vel serve --env production --watch=false

What happens:

1. Starts Vite dev server (if package.json exists)
2. Builds your Go application to .vel/tmp/server
3. Watches all .go files for changes
4. Automatically rebuilds and restarts on file changes

vel build

Build the application for production deployment.

vel build [flags]

Flags:

Examples:

# Default build
vel build

# Custom output path
vel build --output ./bin/myapp

# Cross-compile for Linux
vel build --os linux --arch amd64

vel migrate

Run all pending database migrations.

vel migrate

Requirements:

• Must be run from project root
• Database connection configured in .env

Example output:

MIGRATE

✓ 20240115000001_create_users_table
✓ 20240115000002_create_posts_table

Done

vel migrate:fresh

Drop all database tables and re-run all migrations from scratch.

vel migrate:fresh

vel make:handler

Generate a new HTTP handler.

vel make:handler <name> [flags]

Arguments:

• name - Handler name (automatically converts to snake_case)

Flags:

Examples:

# Basic handler
vel make:handler User

# Resource handler with CRUD methods
vel make:handler Post --resource

# API handler
vel make:handler Product --api --resource

Generated file: internal/handlers/<name>.go

vel key:generate

Generate a new 32-byte encryption key for your application.

vel key:generate [flags]

Flags:

Examples:

# Generate and save to .env
vel key:generate

# Just display the key
vel key:generate --show

The key is saved to the CRYPTO_KEY variable in your .env file.