/craftcms

Console Commands

Documentation

• Commands: https://craftcms.com/docs/5.x/extend/commands.html
• craft\console\Controller: https://docs.craftcms.com/api/v5/craft-console-controller.html
• craft\helpers\Console: https://docs.craftcms.com/api/v5/craft-helpers-console.html

Common Pitfalls

• Setting controllerNamespace after parent::init() in modules — it must come before, or commands are undiscoverable.
• Using raw $this->stdout() with color constants when Craft 5 provides $this->success(), $this->failure(), $this->tip(), $this->warning() with Markdown→ANSI rendering.
• Forgetting parent::options($actionID) — loses --interactive, --color, --help, --isolated.
• Not calling App::maxPowerCaptain() for long-running commands — runs into memory/time limits.
• Missing --isolated for commands that shouldn't run concurrently (sync, import, cleanup).

Contents

• Environment Notes
• Built-in Command Reference
  • Global Options
  • Project and Setup
  • Project Config
  • Sections and Entry Types
  • Fields
  • Content and Elements
  • Cache and Performance
  • Database
  • Users
  • Plugin Management
  • Queue
  • Migrations
  • GraphQL
  • Email
  • Utilities
  • Environment and Shell
  • Other Commands
  • Deployment Recipes
• Generator Commands
• Scaffold
• Arguments and Options
• Rich Output Helpers
• Interactive Prompts
• Progress Bars
• Resave Pattern via EVENT_DEFINE_ACTIONS
• Long-Running Commands
• Command Registration

Environment Notes

Always use ddev craft instead of running craft directly on the host. DDEV executes the command inside the web container where PHP, Composer dependencies, and database connections are available.

When scripting CI/CD pipelines, pass --interactive=0 to all commands so prompts return their defaults without blocking.

Built-in Command Reference

Global Options

Every Craft CLI command supports these inherited options:

Project and Setup

Project Config

The project-config/ controller has a pc/ shorthand alias — craft pc/apply is equivalent to craft project-config/apply.

Sections and Entry Types

Fields

Content and Elements

Common resave flags: --queue (push to queue instead of running inline), --batch-size, --element-id, --uid, --site, --status, --offset, --limit, --update-search-index, --touch (update dateUpdated without re-saving), --set=fieldHandle, --to=value, --to-default (5.10+, writes the field type's default value — requires the field to implement craft\base\DefaultableFieldInterface), --if-empty (only set if field is empty), --if-invalid (only resave elements that fail validation).

Element type-specific flags: --section=blog, --type=post (entries), --volume=images (assets), --group=myGroup (users).

Cache and Performance

Database

Note: search index rebuilding is handled via craft resave/* --update-search-index. Check craft help for the current list of DB commands in your Craft version.

Users

Plugin Management

Queue

For queue architecture and custom job implementation, see queue-jobs.md.

Migrations

GraphQL

Email

Utilities

Environment and Shell

Other Commands

Deployment Recipes

Standard deployment (CI/CD or post-deploy hook):

ddev craft up                    # Migrations + project config
ddev craft clear-caches/all      # Purge stale caches

After content modeling changes (new sections, fields, entry types):

ddev craft project-config/touch  # Force dateModified update
ddev craft up                    # Apply the changes
ddev craft resave/entries --update-search-index  # Re-index affected entries

After search config changes (config/app.php search component):

ddev craft resave/entries --update-search-index   # Rebuild search for entries
ddev craft resave/assets --update-search-index    # Rebuild search for assets

Emergency: project config out of sync with DB:

ddev craft project-config/diff   # See what diverged
ddev craft project-config/rebuild # Rebuild YAML from DB (destructive to YAML)
# Or: ddev craft project-config/apply  # Apply YAML to DB (destructive to DB)

Pre-backup before risky operations:

ddev craft db/backup             # Snapshot to storage/backups/
ddev craft db/backup --zip       # Compressed backup

Generator Commands (craft make)

Craft 5's generator scaffolds boilerplate with correct namespaces, class structure, and optional PHPDoc blocks. Always use --with-docblocks to include section headers and documentation stubs.

ddev craft make <type> --with-docblocks

Available Generators

Generator Tips

• Generators prompt for the target module or plugin — no manual path wrangling needed.
• --with-docblocks adds section headers (// =========================================================================), @author, @since, and @inheritdoc where applicable.
• After scaffolding, customize to match project conventions: add @throws chains, remove unused section headers, and fill in property types.
• For elements, the generator creates both the element class and its query class. You still need to add migration(s) for the content table and register CP routes.

Scaffold

ddev craft make command --with-docblocks

Arguments and Options

Arguments are action method parameters, mapped positionally:

// Usage: ddev craft my-plugin/sync/jobs 42
public function actionJobs(int $instanceId): int
{
    // $instanceId = 42
}

Options are public properties registered via options(). Always call parent first:

public ?string $type = null;
public bool $dryRun = false;

public function options($actionID): array
{
    $options = parent::options($actionID);
    $options[] = 'type';
    $options[] = 'dryRun';
    return $options;
}

public function optionAliases(): array
{
    $aliases = parent::optionAliases();
    $aliases['t'] = 'type';
    $aliases['n'] = 'dryRun';
    return $aliases;
}

Usage: ddev craft my-plugin/sync/jobs --type=widgets -n

Rich Output Helpers (since 4.4.0)

Craft's ControllerTrait provides semantic output methods. All support Markdown formatting (backticks become highlighted, **bold** becomes ANSI bold):

$this->success('Import completed.');              // ✅ prefix
$this->failure('Import failed.');                  // ❌ prefix
$this->tip('Try `ddev craft resave/entries`.');    // 💡 prefix
$this->warning('**Careful** — this is destructive.'); // ⚠️ prefix
$this->note('Custom message.', '🔄 ');            // Custom emoji prefix

Descriptive Actions with do()

Wraps an operation with status output and optional timing:

$this->do('Rebuilding search index', function() {
    // ... expensive work ...
}, withDuration: true);
// Output: → Rebuilding search index … ✓ done (time: 2.341s)

Table Output

$this->table(
    ['ID', 'Title', ['Count', 'align' => 'right']],
    [
        ['1', 'My Entry', '42'],
        ['2', 'Another Entry', '7'],
    ]
);

Raw Output with Colors

When you need low-level control:

use craft\helpers\Console;

$this->stdout("Processing...\n", Console::FG_CYAN);
$this->stderr("Error: not found\n", Console::FG_RED);

Color constants: FG_RED, FG_GREEN, FG_CYAN, FG_YELLOW, FG_GREY. Decorations: BOLD, ITALIC, UNDERLINE.

Interactive Prompts

All respect --interactive=0 (return defaults in non-interactive mode):

// Boolean yes/no
if ($this->confirm('Delete all records?', false)) {
    // proceed
}

// String input with validation
$handle = $this->prompt('Enter handle:', [
    'required' => true,
    'validator' => $this->createAttributeValidator($model, 'handle'),
]);

// Selection from options
$env = $this->select('Choose environment:', [
    'dev' => 'Development',
    'staging' => 'Staging',
    'prod' => 'Production',
]);

// Secure password input
$password = $this->passwordPrompt(['confirm' => true]);

Progress Bars

use craft\helpers\Console;

$items = $this->_fetchItems();
$total = count($items);

Console::startProgress(0, $total, 'Processing: ');
foreach ($items as $i => $item) {
    $this->_processItem($item);
    Console::updateProgress($i + 1, $total);
}
Console::endProgress();

Resave Pattern via EVENT_DEFINE_ACTIONS

Add custom resave commands to Craft's built-in ResaveController — this gives you progress reporting, --queue support, and --set/--to for free:

use craft\console\Controller;
use craft\console\controllers\ResaveController;
use craft\events\DefineConsoleActionsEvent;

Event::on(
    ResaveController::class,
    Controller::EVENT_DEFINE_ACTIONS,
    function(DefineConsoleActionsEvent $event) {
        $event->actions['my-elements'] = [
            'options' => ['type'],
            'helpSummary' => 'Re-saves custom elements.',
            'action' => function(): int {
                $controller = Craft::$app->controller;
                $criteria = [];
                if ($controller->type) {
                    $criteria['type'] = explode(',', $controller->type);
                }
                return $controller->resaveElements(MyElement::class, $criteria);
            },
        ];
    }
);

Usage: ddev craft resave/my-elements --type=widgetType --queue

Long-Running Commands

public function actionImport(): int
{
    App::maxPowerCaptain(); // Raise memory + remove time limit

    $db = Craft::$app->getDb();
    $transaction = $db->beginTransaction();

    try {
        foreach (Db::each($query) as $row) {
            $this->_processRow($row);
        }
        $transaction->commit();
        $this->success('Import completed.');
        return ExitCode::OK;
    } catch (\Throwable $e) {
        $transaction->rollBack();
        $this->failure("Import failed: {$e->getMessage()}");
        return ExitCode::UNSPECIFIED_ERROR;
    }
}

Use Db::each() instead of $query->each() — it handles unbuffered MySQL connections.

Exclusive Execution

Use --isolated to prevent concurrent runs (mutex-based):

// Built-in — just register the option
// Usage: ddev craft my-plugin/sync/jobs --isolated

The --isolated flag is inherited from ControllerTrait and uses Craft's mutex component.

Command Registration

Plugins: Automatic. Place controllers in src/console/controllers/. Commands are accessible as ddev craft plugin-handle/controller/action.

Modules: Must set controllerNamespace before parent::init() AND be bootstrapped in config/app.php. See the main SKILL.md for the pattern.