vel Commands

vel is the per-project binary. It’s created in your project root when you scaffold an app with velocity new. Run ./vel <command> - or alias vel to ./vel in your shell - from the project directory.

For the installer CLI (velocity new, velocity self-update, etc.), see Installer Commands.

Server

vel serve

Start the development server with live reload.

vel serve [flags]

vel serve
vel serve --port 3000
vel serve --env staging --no-watch
vel serve --tags="integration"

On start:

1. Vite dev server launches on :5173 (full-stack projects only).
2. The Go app compiles to .vel/tmp/server.
3. .go files are watched; a change rebuilds and restarts.

vel build

Compile a production binary.

vel build [flags]

vel build
vel build --output ./bin/myapp
vel build --os linux --arch amd64

Database

vel migrate

Run all pending migrations.

vel migrate [--pretend]

--pretend prints the SQL that would run without executing it - useful for reviewing migration output before committing.

vel migrate:fresh

Drop all tables, then run every migration from scratch.

vel migrate:fresh

vel migrate:rollback

Roll back the most recent batch of migrations.

vel migrate:rollback [--step N]

vel migrate:status

Show which migrations have run.

vel migrate:status

vel db:wipe

Drop every table in the current database without running migrations.

vel db:wipe

Queue and Scheduler

vel queue:work

Start a worker that processes queued jobs.

vel queue:work [--queue NAME] [--tries N] [--timeout S]

vel queue:work
vel queue:work --queue emails --tries 3 --timeout 60

vel schedule:work

Run the scheduler loop - picks up scheduled jobs defined via v.Schedule(...) and dispatches them when due.

vel schedule:work

Typically run under a process supervisor (systemd, Docker, etc.) rather than manually.

Cache

vel cache:clear

Flush the configured cache store.

vel cache:clear

Maintenance Mode

vel down

Put the app into maintenance mode. All requests return 503 except those bearing the bypass secret.

vel down [--secret TOKEN] [--retry N]

vel down --secret "abc123" --retry 60

vel up

Exit maintenance mode.

vel up

Keys

vel key:generate

Generate a fresh 32-byte encryption key and write it to .env under CRYPTO_KEY (falls back to APP_KEY if that’s what the project uses).

vel key:generate

Routes

vel route:list

Print every registered route with method, path, name, and middleware.

vel route:list

Rebuilds the bootstrap lifecycle internally before printing - the output always reflects the current v.Routes(...) definition.

Code Generation

All make:* commands scaffold a file into the conventional location for that type. Names are converted to the right case for the artifact (snake_case for migration files, PascalCase for types).

vel make:handler

vel make:handler <name> [--resource] [--api]

Output: internal/handlers/<name>.go.

vel make:handler User
vel make:handler Post --resource
vel make:handler Admin/Dashboard
vel make:handler Product --api --resource

vel make:model

vel make:model <name> [--uuid] [--soft-deletes] [--migration]

Output: internal/models/<name>.go.

vel make:migration

vel make:migration <name> [--create TABLE] [--table TABLE] [--uuid] [--soft-deletes]

Output: database/migrations/<timestamp>_<name>.go.

vel make:migration create_posts --create=posts
vel make:migration add_slug_to_posts --table=posts

Other make commands

All take a name argument and scaffold a file into the conventional directory.

vel make:middleware RateLimit
vel make:listener SendWelcomeEmail
vel make:policy PostPolicy

vel make:grpc:service

vel make:grpc:service <Name>

Scaffolds a gRPC service end-to-end in one call:

• api/proto/<name>/v1/<name>.proto - empty service block
• api/proto/buf.yaml + api/proto/buf.gen.yaml (first run only)
• internal/grpc/services/<name>.go - *<Name>Service impl with UnimplementedXXXServer embed
• internal/providers/grpc_provider.go - created on first call, then injected at // vel:grpc:imports and // vel:grpc:services markers on every subsequent call

Name normalisation: vel make:grpc:service Foo, FooService, foo, and fooService all produce FooService with proto package foo.v1 and Go alias foov1. The proto file uses option go_package = "<module>/api/gen/go/<name>/v1;<name>v1" derived from the host project’s go.mod.

buf.yaml / buf.gen.yaml are written before the proto file, so a config-write failure leaves no partial scaffold on disk. The generated GRPCProvider does not hard-code WithReflection(true); the framework default (toggled by GRPC_REFLECTION env) reaches the file so the generated app boots cleanly in production.

If internal/providers/grpc_provider.go already exists without the marker comments (legacy hand-written provider), the command prints a manual wire snippet instead of mutating user code.

vel make:grpc:service Foo
vel make:grpc:service ChatService

After scaffolding, register providers.GRPCProvider{} in internal/app/bootstrap.go (printed as a hint on first run).

vel make:grpc:rpc

vel make:grpc:rpc <Service> <RPC> [--stream | --client-stream | --bidi]

Appends a new rpc to an existing service’s .proto and a matching method stub on the Go impl. The service must already exist; run vel make:grpc:service <Name> first.

Only one streaming flag may be set per invocation; combining them errors out.

The proto scanner walks the file with brace counting that respects // line comments, /* block */ comments, and "..." string literals at every position (header keyword, between keyword and name, between name and {, and inside the body). That means rpc-with-options blocks (grpc-gateway HTTP annotations) and commented-out draft headers do not corrupt insertion.

On the Go side, the generated method signature matches the RPC shape:

context is added to the impl’s imports for unary only; streaming variants pull ctx from stream.Context() and do not need the import.

Idempotent: re-running with the same <Service> <RPC> pair detects the existing rpc and skips.

vel make:grpc:rpc Foo Hello
vel make:grpc:rpc Foo Tail --stream
vel make:grpc:rpc Foo Upload --client-stream
vel make:grpc:rpc Foo Chat --bidi

vel make:grpc:gen

vel make:grpc:gen

Runs buf generate inside api/proto. Streams buf’s stdout and stderr to your terminal so plugin errors are visible in real time. Fails with a clear message when:

• api/proto/ does not exist (run make:grpc:service first)
• buf is not on PATH (links to install docs)
• buf generate exits non-zero

vel make:grpc:gen
# cd api/proto && buf generate
# Generated Go code in api/gen/go/

Help

vel help
vel --help
vel -h

Prints a grouped list of every command.