VelvetCMS Docs LATEST

CLI Overview

Meet the `velvet` binary, command registry, and developer ergonomics.

Category: CLI & Tooling

Entry point #

./velvet (or php velvet) boots the shared application container (bootstrap/app.php), then hands control to VelvetCMS\Commands\CommandRegistry.

  • Autoload resolution walks up four directories so you can run the binary from packages or workspaces.
  • If bootstrap fails (fresh installs), the script still loads helper functions so install/diagnose commands work offline.
  • When the app resolves, it binds the command registry and fires commands.registering, giving modules a chance to add custom commands.

Registry + signatures #

CommandRegistry::register($name, $class) keeps metadata (optional category, hidden). Once arguments/options are parsed from argv, the registry:

  1. Instantiates the command via the container (fallback reflection if needed).
  2. Injects arguments/options arrays.
  3. Calls handle() and returns the exit code.

Every command extends VelvetCMS\Commands\Command which gives you helpers:

  • $this->argument(0) / $this->option('port') to read CLI input.
  • info/success/warning/error with ANSI colors.
  • Interactive goodies: ask(), confirm(), secret(), choice(), table(), progressBar().

The signature() string is what you see in help output—stick to [--option], <argument>, and [optional] segments for consistency.

Built-in meta commands #

Command Purpose
velvet With no args, prints core + module versions and usage hints.
velvet list Groups all registered commands by category (Setup, Pages, Modules, etc.).
velvet help <command> Displays a command’s description, usage, arguments, and options.
velvet version Reads VersionRegistry for core + module versions, release date, PHP runtime info.

Running commands #

./velvet page:make about-us --title="About Us"
./velvet module:compile
./velvet diagnose --json > health.json

Flags can use either --flag=value or --flag value (the parser stores them as options). Short -f flags are also supported and map to boolean true.

Output conventions #

  • [✓] success, [✗] errors, [!] warnings, [INFO] neutral text.
  • Tables auto-size columns (Command::table()), so use them for human-friendly summaries (pages, modules, diagnostics, etc.).
  • Return codes follow UNIX customs: 0 success, >0 failure.

Extending the CLI #

Modules can register additional commands inside Module::boot() by resolving the CommandRegistry or listening for the commands.registering event. Because the registry lives in the container, you can inject services into your command constructors the same way the core commands do.

That’s the backbone—next pages dig into the high-value commands shipped with the core distribution.

Previous Migrations Next Core Commands