Commands

AppCommand defines the baseline functionality for all of Craft Application’s commands.

class craft_application.commands.base.AppCommand

The AppCommand is a subclass of Craft CLI’s BaseCommand that adds attributes specific to Craft Application.

Metadata

The following attributes provide descriptors that are used when finding a command or showing it in help output.

name: str

The identifier in the command line, like “build” or “pack”.

help_msg: str

A one-line help message for user documentation.

overview: str

Longer, multi-line text with the whole command description.

hidden: bool = False

Do not show in help texts, useful for aliases or deprecated commands (defaults to False).

common: bool = False

Whether this is a common/starter command, which are prioritized in the help (defaults to False).

Argument configuration

fill_parser(parser: _CustomArgumentParser) → None

Specify command’s specific parameters.

Each command parameters are independent of other commands, but note there are some global ones (see main.Dispatcher._build_argument_parser).

If this method is not overridden, the command will not have any parameters.

Parameters:

parser – The object to fill with this command’s parameters.

Runtime Configuration

needs_project(parsed_args: argparse.Namespace) → bool

Property to determine if the command needs a project loaded.

Defaults to always_load_project. Subclasses can override this method.

Parameters:

parsed_args – Parsed arguments for the command.

Returns:

True if the command needs a project loaded, False otherwise.

always_load_project: bool = False

Whether to configure and load the project before starting the command.

Deprecated:

override needs_project() instead.

run_managed(parsed_args: argparse.Namespace) → bool

Whether this command should run in managed mode.

Returns False by default. Subclasses can override this method to change this, including by inspecting the arguments in parsed_args.

provider_name(parsed_args: argparse.Namespace) → str | None

Name of the provider where the command should be run inside of.

Returns None by default. Subclasses can override this method to change this, including by inspecting the arguments in parsed_args.

Execution

run(parsed_args: Namespace) → int | None

Execute command’s actual functionality.

It must be overridden by the command implementation.

Parameters:

parsed_args – The parsed arguments that were defined in fill_parser().

Returns:

This method should return None or the desired process’ return code.

Object access

Each AppCommand instance can access the app’s metadata, its services, and the project.

_app: AppMetadata

The metadata for the running application.

_services: ServiceFactory

The access point for the application’s services.

property _project: Project

Get the current project.

Raises:

Any exception related to rendering the project if the project has not yet been created.

class craft_application.commands.base.ExtensibleCommand(config: dict[str, Any] | None)

Extensible application command.

An ExtensibleCommand is a special type of AppCommand that can be extended with the use of callback functions. It has all of the same attributes and methods of the AppCommand, except that fill_parser and run are marked as final. When implementing or inheriting from an ExtensibleCommand, the equivalent protected methods are available.

_fill_parser(parser: argparse.ArgumentParser) → None

Real parser filler for an ExtensibleCommand.

abstract _run(parsed_args: argparse.Namespace, **kwargs: Any) → int | None

Run the real run method for an ExtensibleCommand.

This allows for the addition of reusable parser fillers, prologues, and epilogues. Each entry in an ExtensibleCommand’s inheritance tree can have exactly one of each.

The following methods can be used to add a parser filler, prologue, and epilogue to a command:

classmethod register_parser_filler(callback: ParserCallback) → None

Register a function that modifies the argument parser.

Only one parser filler callback can be registered to a particular command class. However, fillers registered to parent classes will still be run, from the top class in the inheritance tree on down.

The registered function must be passed the ExtensibleCommand instance as its first argument and the ArgumentParser as its second.

classmethod register_prologue(callback: RunCallback) → None

Register a function that runs before the main run.

Each command class may only have a single prologue. Prologues on the inheritance tree are run in reverse method resolution order. (That is, a child command’s prologue is run after the parent command’s.)

classmethod register_epilogue(callback: RunCallback) → None

Register a function that runs after the main run.

Each command class may only have a single epilogue. Epilogues on the inheritance tree are run in reverse method resolution order. (That is, a child command’s epilogue is run after the parent command’s.)