Commands

Some jobs belong to the application but not to a request: loading sample data, creating the first administrator, rebuilding a cache, sending a nightly digest, exporting a report, applying a data fix. They need the same configuration, database pool and services as the server, and they must be runnable by an operator, a deployment script or a scheduler. Vapor’s answer is that the executable is itself a command line: swift run App starts the server only because serve is the default command, and every other task is another command registered next to it.

Commands are the right tool when a person or a job runner starts the work. They are the wrong tool for work that a user’s request triggers (use a queue for that, see Queues & Background Jobs) and for work that must run every few minutes inside the server (use a scheduled job, see Scheduled Jobs). A command shares the application’s code, so a seeding command can use the same Fluent models and the same Bcrypt configuration as the registration endpoint, and it cannot drift away from them.

A command is a type that conforms to ConsoleKit’s AsyncCommand protocol. The protocol has one associated type and one method:

Source: vapor/console-kit 4.16.1: AsyncCommand.swift

Besides run, the protocol requires var help: String (shown in listings and in --help). The command value must be Sendable, so it is normally a struct without stored state; anything it needs at run time comes from the CommandContext. The Signature is a struct that conforms to CommandSignature, which requires only init() and is also Sendable. Its stored properties, declared with three property wrappers, are the command’s inputs. ConsoleKit finds them by reflection (Mirror) when it parses the command line, in declaration order.

Value for @Argument and @Option must be LosslessStringConvertible & Sendable: String, Int, Double, Bool, a RawRepresentable enum that you make LosslessStringConvertible, and so on. The parsing rules, from CommandInput:

The help strings feed the generated usage text:

Vapor stores commands on app.asyncCommands, a value of ConsoleKit’s AsyncCommands. Register in configure(_:):

Source: Vapor docs: Commands

use(_:as:isDefault:) stores the command under a name; isDefault: true makes it the command that runs when no name is given (serve has that role out of the box). The name is the first non-option token of the command line, so swift run App seed runs seed. enableAutocomplete = true adds an autocomplete command that prints a bash or zsh completion script for the executable. Three commands are present without any code of yours: serve, routes, and migrate once Fluent is configured. serve and routes are described on the Application Lifecycle and the Entrypoint page; the boot command mentioned in older documentation is not registered in 4.122.2 (see that page).

Vapor also keeps an older, synchronous registry, app.commands, for the blocking Command protocol. When the application builds the final command group it merges app.asyncCommands with app.commands, and for a name present in both the entry from app.commands wins. Write new commands as AsyncCommand and register them on app.asyncCommands: a Command blocks the thread that runs it, and you cannot await inside it.

Names are plain strings with no namespace. Use verbs and short, kebab-case names (create-admin), and avoid reusing a built-in name. To group related commands, use AsyncCommandGroup, shown below.

context.console is a Console (by default Terminal, which writes to standard output). The methods you use every day:

Animation and color need an interactive terminal: supportsANSICommands is true only when standard output is a TTY. Piped into a file or a CI log, a progress bar prints two plain lines (Counting [...] then Counting [Done]) and styles are dropped.

Three flags are handled before your command sees the arguments, for every command, so they must not be redefined in a signature:

--yes is what makes a confirming command usable from a deployment script: swift run App migrate --yes applies pending migrations without the y/n> prompt (Fluent’s migrate lists them and asks first). A command that prompts for text with ask or choose, on the other hand, waits for input that a script does not provide (or reads an empty answer at end of input), so any command a script will run needs an input that avoids the prompt, as create-admin does below. The global --env/-e option is not part of this list: Environment.detect() strips it before the commands are parsed, so swift run App seed --env production and swift run App --env production seed both work, and VAPOR_ENV is the fallback.

Bookshelf has three operational needs: sample data for development, the first administrator in a fresh database, and a handful of user-management tasks. The listings use the canonical Bookshelf models (Author, Book, User with email, passwordHash and role) and the CreateBookshelf migration of the Migrations and Schema page. The one change to the application is in configure.swift: a file-based SQLite database, so that separate swift run processes see each other’s data, and the commands registered:

Source: Vapor docs: Commands and Vapor docs: Fluent overview

A fresh database is prepared with swift run App migrate --yes. (The default swift-tools-version 6.3 package of the other pages does not run autoMigrate() in configure; production deployments run migrate as a separate step, see Migrations and Schema.)

A command reports failure by throwing. What the user sees, and the process exit status, are decided by the entrypoint, not by the command. The official template catches the error in entrypoint.swift, reports it with the logger, shuts the application down and rethrows it from main. A Swift program whose main throws terminates with a fatal error, so the run above ended with:

The status was 133 on macOS (a trap, not a clean 1), and the first line appears twice because app.execute() reports the error and the entrypoint’s catch reports it again. That is acceptable in a development terminal but poor for scripts, which want a plain non-zero status and a single message. Replace the final throw error of the template’s catch with an explicit exit:

Source: vapor/template: entrypoint.swift

With that change the same failures exit with status 1. Which error produced the failure is still visible in the message, and ConsoleKit’s own errors are plain CommandError values, not `Abort`s, so they print in their debug form:

A command that wants a friendlier message should catch the expected errors itself, print with console.error(...), and then throw or return according to whether the operation failed: console.error only prints.

The executable is the same one that serves HTTP, so every environment that can run the server can run a command: with the Swift toolchain (swift run App seed), with the built binary (.build/release/App seed), or in the container image (see Deployment with Docker). In a container the arguments after the image name replace the default command, provided the ENTRYPOINT is the binary and the default CMD is serve; this is the layout of the official template’s Dockerfile, so

Source: Vapor docs: Docker

(Not run for this page: no Docker daemon was available. The commands show the shape; check your own image’s entrypoint.) In Kubernetes, a one-off task is a Job with the same image and args: ["migrate", "--yes"], run before the new Deployment rolls out, and a recurring one is a CronJob; see the site’s Jobs and CronJobs page. A command started this way boots the whole application first, including connecting to databases configured in configure, so give the Job the same environment and secrets as the server, and remember that it exits when run returns. For work that has to survive restarts or retry, prefer a queue job (Queues & Background Jobs); for a periodic task you can choose between a scheduled job inside the server (Scheduled Jobs) and a CronJob running a command.

The general VaporTesting setup is on the Testing page. A command is a function of a signature and a console, so it is tested without a process: build a CommandContext with a console that records what the command prints and feeds it prepared answers, set the application on it, and run it through the same Console.run that Application.startup() uses (which is also what applies --help, --yes and --no). Vapor does not ship such a console; ConsoleKit’s Console protocol is small enough to write one:

Source: Vapor docs: Testing and vapor/console-kit 4.16.1: Console.swift

CaptureConsole is Sendable through a lock-protected state box, as Swift 6 requires of a Console. runCommand mirrors startup(): it merges nothing (it uses app.asyncCommands only) and sets context.application. Tests then read like the terminal sessions above:

Source: Vapor docs: Testing

All six tests pass. A few points about them: the configuration uses an in-memory SQLite database and bcrypt cost 4 in the testing environment so that no file is created and hashing is fast; --yes and --password-env are passed as normal arguments; and the password test sets a process environment variable, which is global, so the suite is .serialized. Because the commands call Environment.get, a command that must be tested with different values in parallel should take its configuration from a Sendable struct stored on the application instead of reading the process environment itself.

The Kodeco book (Condon et al., chapter 18) seeds the administrator account with the fixed password "password", and Yeung (chapter 9) publishes ready-made bcrypt hashes to paste in for the same purpose. Both put a credential in the source or the documentation and give every deployment the same administrator, which is exactly what the create-admin command above avoids: the password comes from the operator’s environment and is hashed with the application’s configured hasher at run time. Yeung’s Vapor 3 and Patel’s Vapor 2 predate the current command types; in Vapor 3 commands were registered through a configuration object and the services container, and today they are plain values on app.asyncCommands, with async run methods and Sendable signatures. None of the three covers --yes and --no for scripted runs, command groups, or testing a command without starting a process.