Enable a command plugin

@Metadata { @Available("Swift", introduced: "5.6") }

Extend package manager commands with a command plugin from another package.

Overview

To get access to a plugin from another package, add a dependency on the package that provides the plugin. This lets the package access any plugins from the dependency.

Add a dependency

For example, to enable the plugins from swift-docc-plugin, add it as a dependency:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        // other dependencies
        .package(url: "https://github.com/swiftlang/swift-docc-plugin",
                 from: "1.0.0"),
    ],
    targets: [
        // targets
    ]
)

View available plugins

Run swift package plugin --list to see available plugins. For full documentation on the plugin command, see doc:PackagePlugin.

Invoke an available plugin using swift package followed by the plugin, and provide any parameters or options required. For example, the following command invokes the generate-documentation command from swift-docc-plugin.

swift package generate-documentation

Pass arguments and flags to the plugin

Package manager passes all command line arguments and flags after the invocation verb to the plugin.

For example, if your package has multiple targets you may want to specify a single target with the parameter: --target. An updated example that previews the hypothetical target MyTarget:

swift package generate-documentation --target MyTarget

Exempting sandbox constraints

Command plugins that need to write to the file system cause package manager to ask the user for approval if swift package is invoked from a console, or deny the request if it is not. Pass the flag --allow-writing-to-package-directory to the swift package invocation to allow the request without questions — this is particularly useful in a Continuous Integration environment.

Similarly, use the --allow-network-connections flag to allow network connections without showing a prompt.