Commands¶

Vapor's Command API allows you to build custom command-line functions and interact with the terminal. It is what Vapor's default commands like serve, routes, and migrate are built on.

Default Commands¶

You can learn more about Vapor's default commands using the --help option.

swift run App --help

You can use --help on a specific command to see what arguments and options it accepts.

swift run App serve --help

Xcode¶

You can run commands in Xcode by adding arguments to the App scheme. To do this, follow these steps:

Choose App scheme (to the right of play/stop buttons)
Click "Edit Scheme"
Choose "App" product
Select "Arguments" tab
Add the name of the command to "Arguments Passed On Launch" (i.e., serve)

Custom Commands¶

You can create your own commands by creating types conforming to AsyncCommand.

import Vapor

struct HelloCommand: AsyncCommand {
    ...
}

Adding the custom command to app.asyncCommands will make it available via swift run.

app.asyncCommands.use(HelloCommand(), as: "hello")

To conform to AsyncCommand, you must implement the run method. This requires declaring a Signature. You must also provide default help text.

import Vapor

struct HelloCommand: AsyncCommand {
    struct Signature: CommandSignature { }

    var help: String {
        "Says hello"
    }

    func run(using context: CommandContext, signature: Signature) async throws {
        context.console.print("Hello, world!")
    }
}

This simple command example has no arguments or options, so leave the signature empty.

You can get access to the current console via the supplied context. Console has many helpful methods for prompting user input, output formatting, and more.

let name = context.console.ask("What is your \("name", color: .blue)?")
context.console.print("Hello, \(name) 👋")

Test your command by running:

swift run App hello

Cowsay¶

Take a look at this re-creation of the famous cowsay command for an example of using @Argument and @Option.

import Vapor

struct Cowsay: AsyncCommand {
    struct Signature: CommandSignature {
        @Argument(name: "message")
        var message: String

        @Option(name: "eyes", short: "e")
        var eyes: String?

        @Option(name: "tongue", short: "t")
        var tongue: String?
    }

    var help: String {
        "Generates ASCII picture of a cow with a message."
    }

    func run(using context: CommandContext, signature: Signature) async throws {
        let eyes = signature.eyes ?? "oo"
        let tongue = signature.tongue ?? "  "
        let cow = #"""
          < $M >
                  \   ^__^
                   \  ($E)\_______
                      (__)\       )\/\
                       $T ||----w |
                          ||     ||
        """#.replacingOccurrences(of: "$M", with: signature.message)
            .replacingOccurrences(of: "$E", with: eyes)
            .replacingOccurrences(of: "$T", with: tongue)
        context.console.print(cow)
    }
}

Try adding this to your application and running it.

app.asyncCommands.use(Cowsay(), as: "cowsay")

swift run App cowsay sup --eyes ^^ --tongue "U "