vel Commands

> How the per-project `vel` CLI parses commands, and where each command is documented.

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 Velocity Installer.

Command grammar

Command names are plain words separated by spaces: migrate, migrate fresh, gen model, gen grpc service. Nothing in the CLI uses a colon.

The dispatcher joins the leading arguments into a candidate name (at most three words, the length of the longest registered name) and resolves longest match first:

A subcommand beats its bare parent. vel migrate fresh runs the fresh command; it is never migrate with a fresh argument.
Token joining stops at the first flag-like argument, so vel migrate --pretend resolves to migrate with --pretend handed through as an argument, and vel run report resolves to run with seed (plus any trailing arguments) passed to your custom command.
An unknown command reports the full unmatched token sequence: vel migrate frsh fails with vel: unknown command "migrate frsh", not just migrate.

Unrecognised arguments are rejected rather than silently dropped. An unknown flag errors with unknown flag: <flag>, a stray positional with unexpected argument: <arg>, and a value-taking flag with nothing after it with flag <flag> needs a value. Value-taking flags accept both --flag value and --flag=value.

Arguments are parsed before the application bootstraps, so a typo fails immediately without running your module lifecycle.

Commands

Each command is documented on the page for the feature it drives.

Command	Documented in
`vel serve`	Getting Started
`vel build`	Getting Started
`vel key generate`	Getting Started
`vel migrate`, `migrate fresh`, `migrate rollback`, `migrate status`	Migrations
`vel db seed`, `vel db wipe`	Seeding
`vel queue work`	Queue
`vel schedule work`	Scheduler
`vel cache clear`	Cache
`vel routes`	Routing
`vel down`, `vel up`	Maintenance Mode
`vel run`	Console Commands

Generators

Every generator lives under gen <artifact> and scaffolds one file into the conventional directory for that artifact. All of them accept --dir <path> to write somewhere else; the value must stay inside the project tree and must not route through a symlink. Existing files are never overwritten.

Names are normalised before use: the artifact’s own kind suffix is stripped and the rest is PascalCased, so vel gen policy PostPolicy and vel gen policy Post both write internal/policies/post.go holding type PostPolicy. File names are the snake_case form. Passing nothing but the suffix (vel gen module Module) errors rather than writing a file named .go.

Command	Documented in
`vel gen handler`	Handlers
`vel gen model`	Database: Getting Started
`vel gen migration`	Migrations
`vel gen seeder`	Seeding
`vel gen middleware`	Middleware
`vel gen event`, `vel gen listener`	Events
`vel gen job`	Queue
`vel gen mail`	Mail
`vel gen notification`	Notifications
`vel gen resource`	Resources
`vel gen policy`	Authentication
`vel gen module`	Modules
`vel gen command`	Console Commands
`vel gen grpc service`, `gen grpc rpc`, `gen grpc gen`	gRPC

Help

vel help
vel --help
vel -h

Prints a grouped list of every command: Server, Database, Queue & Scheduler, Cache, Code Generation, Custom Commands, and Other. Running vel with no arguments prints the same listing.