trk / processwire-console
A professional CLI tool for ProcessWire CMS.
Fund package maintenance!
Requires
- php: >=8.3
- ext-ctype: *
- ext-json: *
- ext-mbstring: *
- ext-pdo: *
- dragonmantank/cron-expression: ^3.6
- laravel/prompts: ^0.3
- symfony/console: ^7.0 || ^8.0
Requires (Dev)
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^11.0 || ^12.0 || ^13.0
Suggests
- fakerphp/faker: Generate realistic sample data in database seeders.
Provides
None
Conflicts
None
Replaces
None
README
ProcessWire Console
vendor/bin/wire
A professional CLI for ProcessWire CMS/CMF.
75 production-ready commands · JSON output for AI agents · Composer-driven extensibility
Table of Contents
- Why ProcessWire Console?
- Installation
- Shell Alias (Recommended)
- Quick Start
- Command Reference
- JSON Output (Machine-Readable)
- Interactive Mode
- Extending the Console
- Security
- Architecture
- Requirements
- License
Why ProcessWire Console?
ProcessWire is a powerful CMF but lacks a first-party CLI. This package fills that gap with 75 production-ready commands purpose-built for ProcessWire's architecture:
| Domain | Commands | Description |
|---|---|---|
| Content (Pages) | 9 commands | List, find, create, update, publish, unpublish, move, trash, restore |
| Schema (Fields) | 7 commands | List, info, update, rename, attach, detach, delete |
| Schema (Templates) | 6 commands | List, info, update, rename, reorder fields, delete |
| Modules | 5 commands | List, install, uninstall, refresh, upgrade |
| Users & RBAC | 11 commands | Users, roles, permissions management |
| Cache & Logs | 7 commands | Clear caches, list/read/tail/clear log files |
| Database | 4 commands | Backup, restore, list backups, purge old backups |
| Scaffolding | 6 commands | Generate modules, migrations, queues, seeders, schedules, tests |
| Migrations | 7 commands | Run, rollback, reset, refresh, fresh, status, install |
| Queues | 5 commands | Work, failed, retry, clear, initialize tables |
| Seeding | 1 command | Populate the database with test data |
| Scheduling | 1 command | Run due scheduled tasks |
| Maintenance | 2 commands | Put the application up or down |
| Runtime | 2 commands | Interactive REPL (tinker), version info (version) |
| Testing | 2 commands | Run Pest (test) and Playwright E2E (test:e2e) suites |
| Total | 75 commands |
Every command supports --json for machine-readable output; most mutation commands support --dry-run for safe previews, and destructive commands support --force for non-interactive scripting.
Installation
composer require trk/processwire-console
Composer installs the executable at vendor/bin/wire. Verify installation with:
php vendor/bin/wire list
If the database is not configured, the CLI will still start and display command help. Full functionality requires a working ProcessWire installation with database access.
Shell Alias (Recommended)
Typing php vendor/bin/wire every time is tedious. Set up a shell alias to use just wire:
macOS / Linux (Bash/Zsh)
Add this line to your shell config file (~/.zshrc, ~/.bashrc, or ~/.bash_profile):
# Add ProcessWire Console alias echo 'alias wire="php vendor/bin/wire"' >> ~/.zshrc && source ~/.zshrc
For Bash users, replace
~/.zshrcwith~/.bashrc.
Windows (PowerShell)
Run in PowerShell to add a persistent alias:
# Create profile if it doesn't exist, then add alias if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -Force } Add-Content $PROFILE 'function wire { php vendor/bin/wire @args }' . $PROFILE
Windows (CMD)
Create a wire.bat file in a directory that's in your PATH:
@echo off php vendor/bin/wire %*
After Setup
Now you can use wire directly:
# Before php vendor/bin/wire page:list --template=basic-page # After ✨ wire page:list --template=basic-page wire user:create -i wire migrate:status
Quick Start
# List all available commands php vendor/bin/wire list # Get detailed help for any command php vendor/bin/wire help page:create # Create a page php vendor/bin/wire page:create --parent=/ --template=basic-page --title="Hello World" # List pages as JSON php vendor/bin/wire page:list --template=basic-page --json # Create a user with roles php vendor/bin/wire user:create # Backup the database php vendor/bin/wire db:backup # Interactive REPL php vendor/bin/wire tinker # Start Queue Worker php vendor/bin/wire queue:work
Command Reference
Pages
Manage the ProcessWire page tree — create, update, publish, move, trash, and restore pages.
page:list
List pages with filtering, sorting, and pagination.
# List the 20 most recent pages php vendor/bin/wire page:list # Filter by template and parent php vendor/bin/wire page:list --template=blog-post --parent=/blog/ --limit=50 # Sort by title ascending php vendor/bin/wire page:list --sort=title --limit=10 # Include hidden and unpublished pages php vendor/bin/wire page:list --include=all # JSON output for scripting php vendor/bin/wire page:list --template=product --json
Options:
| Option | Short | Description |
|---|---|---|
--template |
-t |
Filter by template name |
--parent |
-p |
Filter by parent path or ID |
--sort |
-s |
Sort field (default: -created). Prefix with - for descending |
--limit |
-l |
Number of results (default: 20) |
--include |
-i |
Include scope: all, hidden, unpublished (default: all) |
--json |
Output as JSON |
page:find
Find pages using a raw ProcessWire selector string.
php vendor/bin/wire page:find "template=blog-post, title%=ProcessWire, limit=10" # JSON output php vendor/bin/wire page:find "parent=/products/, sort=-created, limit=5" --json
Options:
| Option | Short | Description |
|---|---|---|
selector |
Argument: ProcessWire selector string | |
--limit |
-l |
Maximum number of results when not set in selector (default: 50) |
--json |
Output as JSON |
page:create
Create a new page under a parent with a specific template.
# Basic creation php vendor/bin/wire page:create --parent=/ --template=basic-page --title="About Us" # Create as unpublished php vendor/bin/wire page:create --parent=/blog/ --template=blog-post --title="Draft Post" --unpublished # Fully interactive mode — prompts for template, parent, title, and all fields php vendor/bin/wire page:create -i # Preview without saving php vendor/bin/wire page:create --parent=/ --template=basic-page --title="Test" --dry-run
Options:
| Option | Short | Description |
|---|---|---|
--parent |
-p |
Parent page path or ID (required) |
--template |
-t |
Template name (required) |
--title |
Page title | |
--name |
URL-safe name (auto-generated from title if omitted) | |
--unpublished |
Create as unpublished | |
--interactive |
-i |
Prompt for all values including template field filling |
--dry-run |
Preview changes without saving | |
--json |
Output as JSON |
page:update
Update page properties and field values.
# Update title php vendor/bin/wire page:update --id=1042 --title="New Title" # Set arbitrary fields with --set php vendor/bin/wire page:update --id=1042 --set="summary=Updated summary" --set="body=New body content" # Change page status php vendor/bin/wire page:update --id=1042 --status=hidden # Move and rename php vendor/bin/wire page:update --id=1042 --parent=/another-parent/ --name=new-url-name # Preview changes php vendor/bin/wire page:update --id=1042 --title="Preview" --dry-run
Options:
| Option | Description |
|---|---|
--id |
Page ID (required; or use --path) |
--path |
Page path (alternative to --id) |
--title |
New title |
--name |
New URL-safe name |
--parent |
New parent path or ID |
--template |
Change template |
--status |
Status: publish/published, unpublish/unpublished, hide/hidden, show, lock/locked, unlock/unlocked |
--set |
Set field value as key=value (repeatable) |
-i, --interactive |
Prompt interactively for status and field edits |
--dry-run |
Preview without saving |
--json |
Output as JSON |
page:publish / page:unpublish
php vendor/bin/wire page:publish --id=1042 php vendor/bin/wire page:unpublish --path=/about/ php vendor/bin/wire page:publish --id=1042 --dry-run --json
page:trash / page:restore
php vendor/bin/wire page:trash --id=1042
php vendor/bin/wire page:trash --path=/drafts/old/ --dry-run
php vendor/bin/wire page:restore --id=1042 --dry-run
# Force without confirmation
php vendor/bin/wire page:trash --id=1042 --force --json
page:move
php vendor/bin/wire page:move --id=1042 --parent=/new-section/ php vendor/bin/wire page:move --path=/about/ --parent=1001 --dry-run --json
Fields
Full lifecycle management for ProcessWire fields.
field:list
# List all fields php vendor/bin/wire field:list # Filter by type php vendor/bin/wire field:list --type=FieldtypeText # Search by name or label php vendor/bin/wire field:list --search=body # JSON output php vendor/bin/wire field:list --json
field:info
php vendor/bin/wire field:info --name=body php vendor/bin/wire field:info --name=body --json
field:update
# Update label and description (supports --dry-run and --json) php vendor/bin/wire field:update --name=body --set="label=Body Text" --set="description=Main content area" # Preview field setting changes without writing php vendor/bin/wire field:update --name=summary --set="maxlength=500" --set="required=1" --dry-run
field:rename
php vendor/bin/wire field:rename --name=old_field_name --new-name=new_field_name php vendor/bin/wire field:rename --name=body --new-name=content --dry-run
field:attach / field:detach
# Attach a field to a template (supports --position=first|last|after=FIELD|before=FIELD and --dry-run) php vendor/bin/wire field:attach --template=blog-post --field=images --position=first # Attach after a specific field php vendor/bin/wire field:attach --template=blog-post --field=tags --after=body --dry-run # Detach a field from a template php vendor/bin/wire field:detach --template=blog-post --field=sidebar --force php vendor/bin/wire field:detach --template=blog-post --field=sidebar --dry-run --json
field:delete
php vendor/bin/wire field:delete --name=unused_field --dry-run php vendor/bin/wire field:delete --name=unused_field --force --json
Templates
template:list
php vendor/bin/wire template:list php vendor/bin/wire template:list --tag=content --search=blog --json
template:info
php vendor/bin/wire template:info --name=basic-page php vendor/bin/wire template:info --name=basic-page --json
template:update
php vendor/bin/wire template:update --name=blog-post --set="label=Blog Article" php vendor/bin/wire template:update --name=blog-post --set="noChildren=1" --set="noParents=-1" --dry-run
template:rename
php vendor/bin/wire template:rename --name=old-template --new-name=new-template php vendor/bin/wire template:rename --name=old-template --new-name=new-template --dry-run
template:fields:reorder
# Reorder fields within a template (supports --dry-run and --json) php vendor/bin/wire template:fields:reorder --template=blog-post --fields="title,body,images,tags,summary" php vendor/bin/wire template:fields:reorder --template=blog-post --fields="title,body" --dry-run
template:delete
php vendor/bin/wire template:delete --name=unused-template --dry-run php vendor/bin/wire template:delete --name=unused-template --force
Modules
A complete module lifecycle manager — discover, install, uninstall, refresh, upgrade.
module:list
# List all installed modules php vendor/bin/wire module:list # Core modules only php vendor/bin/wire module:list --core # Site (third-party) modules only php vendor/bin/wire module:list --site # Search php vendor/bin/wire module:list --search=Image # JSON output php vendor/bin/wire module:list --site --json
module:install / module:uninstall
php vendor/bin/wire module:install --name=ModuleName --dry-run php vendor/bin/wire module:install --name=ModuleName php vendor/bin/wire module:uninstall --name=ModuleName --dry-run php vendor/bin/wire module:uninstall --name=ModuleName --force
module:refresh
# Refresh all module caches php vendor/bin/wire module:refresh # Refresh a specific module php vendor/bin/wire module:refresh --name=ModuleName
module:upgrade
php vendor/bin/wire module:upgrade --name=ModuleName
Users & RBAC
Complete role-based access control management from the command line.
Users
# List all users (supports --search, --role, --limit, --json) php vendor/bin/wire user:list php vendor/bin/wire user:list --search=john --role=editor --limit=25 --json # Create a user (interactive prompts for password, email, roles; also accepts <username> <email>, -i/--interactive, -p/--password, repeatable -r/--role) php vendor/bin/wire user:create # Create a user non-interactively php vendor/bin/wire user:create --name=john --email=john@example.com --password=SecretPass --role=editor --force # Update a user (supports --id, --name, --email, --password, --add-role, --remove-role, --dry-run, --force, --json) php vendor/bin/wire user:update --name=john --email=new@example.com --dry-run php vendor/bin/wire user:update --id=1045 --password=UpdatedSecret --add-role=editor --remove-role=author --force # Delete a user php vendor/bin/wire user:delete --name=john --dry-run php vendor/bin/wire user:delete --id=1045 --force --json
Roles
# List roles php vendor/bin/wire role:list php vendor/bin/wire role:list --json # Create a role (supports --permissions and -i/--interactive) php vendor/bin/wire role:create --name=editor --title="Content Editor" --permissions="page-view,page-edit" # Grant or revoke a permission on a role (supports --dry-run and --json) php vendor/bin/wire role:grant --role=editor --permission=page-edit --dry-run php vendor/bin/wire role:revoke --role=editor --permission=page-delete
Permissions
# List permissions php vendor/bin/wire permission:list # Create a custom permission php vendor/bin/wire permission:create --name=my-custom-permission --title="Custom Permission" # Delete a custom permission php vendor/bin/wire permission:delete --name=my-custom-permission --dry-run php vendor/bin/wire permission:delete --name=my-custom-permission --force --json
Cache
cache:clear
Clears module caches and compiled FileCompiler template files.
php vendor/bin/wire cache:clear php vendor/bin/wire cache:clear --json
cache:wire:clear
Clear WireCache entries by exact key or SQL LIKE pattern.
# Clear a specific cache key php vendor/bin/wire cache:wire:clear --key=MyModule.someData # Clear all cache entries matching a pattern php vendor/bin/wire cache:wire:clear --pattern="Template%" php vendor/bin/wire cache:wire:clear --pattern="MyModule.%" --json
Logs
log:list
List all available log files.
php vendor/bin/wire log:list php vendor/bin/wire log:list --json
log:read
Retrieve and display ProcessWire logs as a formatted table.
# Read 'errors' log php vendor/bin/wire log:read errors # Read with a specific date range and sort order (asc|desc) php vendor/bin/wire log:read messages --from="2026-04-01" --to="today" --sort=desc # Limit output and filter by string php vendor/bin/wire log:read errors --limit=50 --find="Exception" # JSON output php vendor/bin/wire log:read errors --json
log:tail
Read the last N lines of a log file and follow output.
# Read errors.txt (last 200 lines by default) php vendor/bin/wire log:tail errors # Read fewer lines php vendor/bin/wire log:tail exceptions --lines=20 # Follow output (like tail -f) php vendor/bin/wire log:tail messages --follow # JSON output php vendor/bin/wire log:tail errors --json
log:clear
Clear one or more ProcessWire log files.
php vendor/bin/wire log:clear errors --dry-run php vendor/bin/wire log:clear errors exceptions --force --json
log:clear-all
Clear all ProcessWire log files.
php vendor/bin/wire log:clear-all --dry-run php vendor/bin/wire log:clear-all --force --json
Database & Backup
db:backup
Create a database backup using ProcessWire's native WireDatabaseBackup.
php vendor/bin/wire db:backup php vendor/bin/wire db:backup --json
db:restore
Restore the database from a backup file.
php vendor/bin/wire db:restore --file=backup-2026-04-08.sql --dry-run php vendor/bin/wire db:restore --file=backup-2026-04-08.sql --force
Warning: This operation replaces your entire database. Always back up before restoring.
backup:list
php vendor/bin/wire backup:list php vendor/bin/wire backup:list --limit=20 --json
backup:purge
Remove old backup files by count (--keep) or age (--days, default 30).
# Keep the 5 most recent backups php vendor/bin/wire backup:purge --keep=5 # Delete backups older than 14 days php vendor/bin/wire backup:purge --days=14 --dry-run php vendor/bin/wire backup:purge --keep=3 --force
Scaffolding
make:module
Scaffold a new ProcessWire module from a professional stub.
# Standard module php vendor/bin/wire make:module HelloWorld # Fieldtype module php vendor/bin/wire make:module FieldtypeColor --type=fieldtype # Inputfield module php vendor/bin/wire make:module InputfieldColor --type=inputfield # Process (admin page) module php vendor/bin/wire make:module ProcessDashboard --type=process # With custom metadata php vendor/bin/wire make:module MyModule \ --type=module \ --title="My Custom Module" \ --summary="Does amazing things" \ --author="Developer Name" \ --mod-version=0.1.0 \ --autoload
Module types and stubs:
| Type | Base Class | Use Case |
|---|---|---|
module |
WireData |
General-purpose module with init/ready hooks |
fieldtype |
Fieldtype |
Custom database field storage |
inputfield |
Inputfield |
Custom form input widget |
process |
Process |
Admin page with URL routing |
make:migration
Scaffold a new timestamped migration file. See Migrations for full documentation.
php vendor/bin/wire make:migration create_blog_section php vendor/bin/wire make:migration add_body_field --type=create-field --field=body
make:queue
Generate a new file-based Queue class (site/queue/ or site/modules/<Module>/queue/).
php vendor/bin/wire make:queue SendEmailQueue php vendor/bin/wire make:queue CompileImagesQueue --module=ProcessAnalytics
Options:
| Option | Short | Description |
|---|---|---|
name |
Class name (auto-suffixed with Queue if omitted) |
|
--module |
-m |
Place inside site/modules/<Module>/queue/ |
--json |
Output as JSON |
See also
make:seeder,make:test, andmake:taskin their respective sections.
Migrations
A complete migration system for ProcessWire — schema versioning with up/down methods, batch tracking, rollback support, and 7 typed stubs for common PW operations.
Migrations live in site/migrations/ and are tracked in the wire_migrations database table (auto-created on first run).
make:migration
Generate a new timestamped migration file from a stub.
# Blank migration (pass -m/--module=ModuleName on schema/page types to scaffold into site/modules/<ModuleName>/migrations/) php vendor/bin/wire make:migration create_blog_section php vendor/bin/wire make:migration add_blog_schema --module=SiteBlog # Create a field php vendor/bin/wire make:migration add_subtitle_field --type=create-field --field=subtitle --fieldtype=FieldtypeText # Create a template php vendor/bin/wire make:migration create_blog_template --type=create-template --template=blog-post --label="Blog Post" # Attach field to template php vendor/bin/wire make:migration attach_images_to_blog --type=attach-field --template=blog-post --field=images # Create a page php vendor/bin/wire make:migration create_about_page --type=create-page --template=basic-page --parent=/ --label="About Us" # Create a role with permissions php vendor/bin/wire make:migration create_editor_role --type=create-role --role=editor --label="Content Editor" # Install a module php vendor/bin/wire make:migration install_redirects_module --type=install-module --module=ProcessRedirects
Stub types:
--type |
Generates | up() | down() |
|---|---|---|---|
blank |
Empty skeleton (default) | — | — |
create-field |
Field creation | new Field() + save |
delete field |
create-template |
Template + fieldgroup + file | Full scaffold | delete template + file |
attach-field |
Field-to-template attachment | fieldgroup add | fieldgroup remove |
create-page |
Page creation | $pages->newPage() + save |
delete page |
create-role |
Role + permission grants | roles add + grant | delete role |
install-module |
Module install | modules->install() |
uninstall |
Dependency Order (Critical)
ProcessWire objects have strict dependency chains. Migrations must respect this order:
CREATE order: Field → Fieldgroup → Template → Page
DELETE order: Page → Template → Fieldgroup → Field
For a typical blog setup, the correct migration sequence is:
# 1. Create fields first php vendor/bin/wire make:migration create_body_field --type=create-field --field=body php vendor/bin/wire make:migration create_summary_field --type=create-field --field=summary # 2. Create template (depends on fields existing) php vendor/bin/wire make:migration create_blog_template --type=create-template --template=blog-post # 3. Attach fields to template php vendor/bin/wire make:migration attach_body_to_blog --type=attach-field --template=blog-post --field=body php vendor/bin/wire make:migration attach_summary_to_blog --type=attach-field --template=blog-post --field=summary # 4. Create pages last (depends on template existing) php vendor/bin/wire make:migration create_blog_page --type=create-page --template=blog-post --parent=/
On rollback, these run in reverse order (last-in-first-out) — pages deleted before templates, fields detached before being deleted.
Safe-by-Default Guards
All stubs include precondition guards in down() that throw clear errors instead of cascading destructive operations:
| Stub | Guard | Error |
|---|---|---|
create-field |
Field attached to template(s)? | "Cannot delete — detach first" |
create-template |
Pages using this template? | "Cannot delete — remove pages first" |
attach-field |
Pages have data in this field? | "Cannot detach — data would be lost" |
create-page |
Page has children? | "Cannot delete — remove children first" |
create-role |
Users assigned this role? | "Cannot delete — remove from users first" |
install-module |
Other modules depend on it? | "Cannot uninstall — dependencies exist" |
Design philosophy: Stubs never auto-delete user content or cascade-remove dependencies. They fail loudly so you can write the correct cleanup migration yourself.
Each migration file returns an anonymous class with up() and down() methods:
<?php declare(strict_types=1); namespace ProcessWire; return new class { public function up(): void { $field = new Field(); $field->type = wire('modules')->get('FieldtypeText'); $field->name = 'subtitle'; $field->label = 'Subtitle'; wire('fields')->save($field); } public function down(): void { $field = wire('fields')->get('subtitle'); if (!$field || !$field->id) { return; } // Guard: field must not be attached to any template $fieldgroups = $field->getFieldgroups(); if ($fieldgroups->count() > 0) { $names = $fieldgroups->implode(', ', 'name'); throw new WireException( "Cannot delete field 'subtitle' — attached to: {$names}. Detach first." ); } wire('fields')->delete($field); } };
migrate
Run all pending migrations.
# Apply all pending php vendor/bin/wire migrate # Apply one at a time php vendor/bin/wire migrate --step=1 # Preview without applying php vendor/bin/wire migrate --dry-run # Non-interactive php vendor/bin/wire migrate --force # JSON output php vendor/bin/wire migrate --json
migrate:rollback
Rollback the last batch of migrations (calls down() in reverse order).
# Rollback last batch php vendor/bin/wire migrate:rollback --force # Rollback last 3 individual migrations php vendor/bin/wire migrate:rollback --step=3 --force --json # Preview php vendor/bin/wire migrate:rollback --dry-run
migrate:reset
Rollback ALL applied migrations.
php vendor/bin/wire migrate:reset --dry-run php vendor/bin/wire migrate:reset --force --json
migrate:refresh
Reset + re-run all migrations (shortcut for reset then migrate).
php vendor/bin/wire migrate:refresh --dry-run php vendor/bin/wire migrate:refresh --force --json
migrate:fresh
Drop the tracking table entirely and re-run all migrations from scratch.
php vendor/bin/wire migrate:fresh --dry-run php vendor/bin/wire migrate:fresh --force --json
Warning:
migrate:freshdoes not calldown()— it drops the tracking table and re-applies all migrations. Usemigrate:refreshif you need clean rollbacks.
migrate:status
Show the status of all migration files in a formatted table.
php vendor/bin/wire migrate:status php vendor/bin/wire migrate:status --json
Output example:
+---------------------------------------------+---------+-------+
| Migration | Status | Batch |
+---------------------------------------------+---------+-------+
| 20260408120000_create_blog_template.php | Applied | 1 |
| 20260408120100_add_featured_image_field.php | Applied | 1 |
| 20260408120200_create_editor_role.php | Pending | - |
+---------------------------------------------+---------+-------+
! [NOTE] 2 applied, 1 pending.
migrate:install
Explicitly create the wire_migrations tracking table (auto-created by migrate if missing).
php vendor/bin/wire migrate:install
Queues
ProcessWire Console offers a lightweight, database-backed Queue Management System that automatically discovers *Queue.php classes.
queue:table
Create the database tables (queue_jobs and failed_jobs) required to store queue data.
php vendor/bin/wire queue:table
queue:work
Start the queue worker daemon to process background jobs continually (or process a single job with --once).
php vendor/bin/wire queue:work --queue=default --sleep=3 --tries=3 php vendor/bin/wire queue:work --once --json
Options:
| Option | Description |
|---|---|
--queue |
Name of the queue (default: default) |
--sleep |
Seconds to wait before polling again when empty (default: 3) |
--tries |
Attempts before moving a job to failed_jobs (default: 3) |
--memory |
Worker memory limit in megabytes before graceful exit (default: 128) |
--once |
Process only the next available job and exit |
--json |
Output as JSON |
queue:failed
List recent failed jobs cleanly in a table.
php vendor/bin/wire queue:failed --limit=50 php vendor/bin/wire queue:failed --json
queue:retry
Push a failed job back onto the queue for processing, or bulk retry all.
php vendor/bin/wire queue:retry 12 php vendor/bin/wire queue:retry all
queue:clear
Wipe all records from the failed_jobs table.
php vendor/bin/wire queue:clear --dry-run php vendor/bin/wire queue:clear --force --json
Database Seeding
Populate your database with initial data or fake data using ProcessWire Console.
Tip: If you need fake data generation, it is highly recommended to install Faker via
composer require fakerphp/faker. The base Seeder class will automatically inject a Faker instance for you to use via$this->faker. You can also just parse local JSON files natively.
make:seeder
Generate a new seeder stub.
php vendor/bin/wire make:seeder UsersSeeder php vendor/bin/wire make:seeder DemoProductsSeeder --module=Shop
db:seed
Run the database seeders. It auto-discovers seeders in site/seeders/ and site/modules/*/seeders/.
# Preview seeders without running them php vendor/bin/wire db:seed --dry-run # Run all discovered seeders php vendor/bin/wire db:seed --force --json # Run a specific seeder class php vendor/bin/wire db:seed --class=UsersSeeder --force
Testing
ProcessWire Console integrates Pest PHP natively to bring beautiful, modern Test-Driven Development (TDD) to ProcessWire.
Tip: If Pest is not installed on your system when you run the
testcommand, the console will detect it and elegantly prompt you to install it and automatically scaffold thetests/Pest.phpconfig.
Our intelligent FeatureDiscoverer auto-magically locates all Pest tests placed in:
/tests//site/tests//site/modules/[AnyActiveModule]/tests/
...and runs them holistically via a single command!
make:test
Generate a new Pest PHP test or Playwright E2E spec stub.
# Create a Feature test in site/tests/Feature/ php vendor/bin/wire make:test UserLoginTest # Create a Unit test in site/tests/Unit/ php vendor/bin/wire make:test DataSyncTest --unit # Create a Pest test inside a specific module's tests/ directory php vendor/bin/wire make:test SyncService --module=ProcessAnalytics # Create a Playwright E2E spec in site/tests/e2e/workspace-flow.spec.ts php vendor/bin/wire make:test WorkspaceFlow --e2e # Create a Playwright E2E spec inside a module -> site/modules/Blog/tests/e2e/entries-flow.spec.ts php vendor/bin/wire make:test EntriesFlow --e2e --module=Blog
test
Run your Pest test suite. You can pass forward any native Pest arguments (e.g., --filter, --parallel).
# Run all discovered tests across the system and active modules php vendor/bin/wire test # Run tests and filter for "Login" php vendor/bin/wire test --filter=Login
test:e2e
Run optional Playwright end-to-end browser and WCAG 2.1 AA accessibility suites across /tests/e2e/, /site/tests/e2e/, /site/templates/tests/e2e/, and active /site/modules/<Module>/tests/e2e/ directories.
Tip: On first run (or via
--init),test:e2ecan interactively install@playwright/test+@axe-core/playwrightand scaffoldplaywright.config.tsalongsidetests/e2e/{global-setup,global-teardown,helpers}.tswith ephemeral ProcessWire superuser authentication.
# Scaffold Playwright config and ProcessWire E2E helpers without running tests php vendor/bin/wire test:e2e --init # Run E2E specs across site and all installed ProcessWire modules php vendor/bin/wire test:e2e # Run E2E specs only for a specific installed module php vendor/bin/wire test:e2e --module=ProcessAnalytics # Forward native Playwright flags (--headed, --ui, --grep, --project, etc.) php vendor/bin/wire test:e2e --module=Blog --grep="Workspace"
Task Scheduling
Manage scheduled, recurring tasks from a single cron entry using dragonmantank/cron-expression.
Cron Configuration: Add a single entry to your server's crontab that runs every minute:
* * * * * cd /path/to/project && php vendor/bin/wire schedule:run >> /dev/null 2>&1
make:task
Generate a new scheduled task stub.
php vendor/bin/wire make:task SyncDataTask php vendor/bin/wire make:task CleanupTask --module=AppAdmin
schedule:run
Evaluate and run any scheduled tasks that are currently due.
php vendor/bin/wire schedule:run
Maintenance Mode
Easily put your application into a maintenance or disabled state.
Requirement: For ProcessWire to intercept HTTP requests during maintenance mode, add the following check to site/init.php:
<?php declare(strict_types=1); namespace ProcessWire; $downFile = $config->paths->site . 'down.json'; $reqPath = (string) (parse_url($_SERVER['REQUEST_URI'] ?? '/', PHP_URL_PATH) ?: '/'); if (!$config->cli && is_file($downFile) && !is_link($downFile) && !str_starts_with($reqPath, $config->urls->admin)) { $down = json_decode((string) file_get_contents($downFile), true) ?: []; $secret = (string) ($down['secret'] ?? ''); $querySecret = $input->get->text('secret'); $provided = $querySecret !== '' ? $querySecret : (string) $session->get('maintenance_secret'); if ($secret !== '' && hash_equals($secret, $provided)) { $session->set('maintenance_secret', $secret); } else { $redirect = (string) ($down['redirect'] ?? ''); $redirectPath = (string) (parse_url($redirect, PHP_URL_PATH) ?: ''); if ($redirect !== '' && $reqPath !== $redirectPath) { $session->redirect($redirect, false); } if (!empty($down['retry'])) { header('Retry-After: ' . (int) $down['retry']); } http_response_code((int) ($down['status'] ?? 503)); exit('Service Unavailable'); } }
down
Put the application into maintenance mode (site/down.json).
# Basic down php vendor/bin/wire down # Retry-After seconds and custom HTTP status php vendor/bin/wire down --retry=300 --status=503 # With a bypass secret (?secret=dev123) php vendor/bin/wire down --secret=dev123 # Redirect visitors to another URL php vendor/bin/wire down --redirect=https://status.example.com
up
Bring the application out of maintenance mode.
php vendor/bin/wire up
Tinker (REPL)
An interactive ProcessWire PHP REPL (or one-shot expression evaluator) for quick testing and debugging.
# Interactive REPL php vendor/bin/wire tinker # Evaluate a single PHP expression and return JSON php vendor/bin/wire tinker '$pages->count("template=basic-page")' --json
ProcessWire Tinker — type "exit" to quit.
>>> $pages->count("template=basic-page")
12
>>> $user->name
admin
>>> $config->urls->templates
/site/templates/
Security: Set
PW_CLI_DISABLE_TINKER=1in production environments to disable this command.
Version
Show the active version of PHP, ProcessWire, trk/processwire-console, and installed companion packages such as trk/processwire-boost.
php vendor/bin/wire version php vendor/bin/wire version --json php vendor/bin/wire -V
JSON Output (Machine-Readable)
Every command supports the --json flag for machine-readable output. This makes ProcessWire Console first-class for CI/CD pipelines, AI agent integrations, and automation scripts.
Response format:
{
"ok": true,
"data": {
"items": [],
"total": 0
}
}
Error format:
{
"ok": false,
"error": {
"code": "NOT_FOUND",
"message": "Page not found: /nonexistent"
}
}
Examples:
# Pipe page data to jq php vendor/bin/wire page:list --template=blog-post --json | jq '.data.items[].title' # Count modules php vendor/bin/wire module:list --site --json | jq '.data.total' # Use in shell scripts BACKUP=$(php vendor/bin/wire db:backup --json | jq -r '.data.file') echo "Backup saved to: $BACKUP"
Interactive Mode
Commands that create or modify data support interactive prompts powered by laravel/prompts:
page:create -i— Select template from a list, enter parent path, fill template fields interactivelyuser:create— Prompts for username, email, password (with confirmation), and role selection
Interactive prompts are automatically disabled when:
- The
--jsonflag is present - The
--forceflag is present - The terminal is non-interactive (piped input)
Extending the Console
Method 1: Module Feature Auto-Discovery
ProcessWire Console features a centralized FeatureDiscoverer that automatically locates and registers CLI assets from the root site/ directory and exclusively from installed/active modules. If a module is inactive or uninstalled, its CLI features are safely ignored.
Place the corresponding files inside the target hierarchy (site/... or site/modules/[ModuleName]/...):
commands/— Drop-in Symfony Console commands (*Command.php)migrations/— Database migrations (*_[name].php)seeders/— Database seeders (*Seeder.php)schedule/— Scheduled cron tasks (*Task.php)queue/— Background queue jobs (*Queue.php)
They are automatically discovered and loaded on every CLI invocation.
<?php declare(strict_types=1); // site/commands/SyncProductsCommand.php namespace Site\Commands; use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Input\InputOption; use Symfony\Component\Console\Output\OutputInterface; use Totoglu\Console\Traits\InteractWithProcessWire; use function Laravel\Prompts\info; use function ProcessWire\wire; final class SyncProductsCommand extends Command { use InteractWithProcessWire; protected function configure(): void { $this ->setName('products:sync') ->setDescription('Synchronize products from external API.') ->addOption('json', null, InputOption::VALUE_NONE, 'JSON output'); } protected function execute(InputInterface $input, OutputInterface $output): int { $asJson = (bool) $input->getOption('json'); $count = wire('pages')->count('template=basic-page'); if ($asJson) { return $this->outputJsonSuccess($output, ['synced' => $count]); } info("Synchronized {$count} items."); return Command::SUCCESS; } }
Method 2: Composer Package Discovery
Register commands in your package's composer.json:
{
"name": "vendor/my-pw-package",
"extra": {
"processwire-console": {
"commands": [
"Vendor\\MyPackage\\Commands\\ImportCommand",
"Vendor\\MyPackage\\Commands\\ExportCommand"
]
}
},
"autoload": {
"psr-4": {
"Vendor\\MyPackage\\": "src/"
}
}
}
The console engine reads vendor/composer/installed.json and root composer.json path repositories to discover commands automatically.
Security
Path Traversal Protection
Log commands (log:tail, log:read, log:clear) reject path separators (/, \) and .. traversal sequences (INVALID_NAME) and refuse to follow symbolic links.
Tinker Guard
The tinker command executes arbitrary PHP via eval(). To disable it in production:
export PW_CLI_DISABLE_TINKER=1
Confirmation Prompts
All destructive commands (*:delete, *:trash, field:detach, module:uninstall, db:restore, db:seed, backup:purge, log:clear, log:clear-all, queue:clear, migrate:rollback, migrate:reset, migrate:refresh, migrate:fresh) require explicit confirmation. Use --force to bypass for scripting.
Migration Safety
Migration stubs enforce safe-by-default guards in down() — they never cascade-delete user content. If a field is in use, a template has pages, or a role is assigned to users, the rollback will throw a descriptive WireException instead of silently destroying data. See Safe-by-Default Guards for details.
Dry-Run Mode
Preview supported mutations with --dry-run:
php vendor/bin/wire page:update --id=1042 --title="Test" --dry-run
php vendor/bin/wire template:delete --name=old-template --dry-run
php vendor/bin/wire db:restore --file=backup.sql --dry-run
Architecture
processwire-console/
├── bin/
│ └── wire # CLI entry point (bootstrap + command registration)
├── src/
│ ├── Commands/ # 75 command classes
│ │ ├── Page*.php # 9 page management commands
│ │ ├── Field*.php # 7 field management commands
│ │ ├── Template*.php # 6 template management commands
│ │ ├── Module*.php # 5 module lifecycle commands
│ │ ├── User*.php # 4 user commands
│ │ ├── Role*.php # 4 role commands
│ │ ├── Permission*.php # 3 permission commands
│ │ ├── Migrate*.php # 7 migration commands
│ │ ├── Queue*.php # 5 queue commands
│ │ ├── Cache*.php # 2 cache commands
│ │ ├── Log*.php # 5 log commands
│ │ ├── Db*.php # 3 database & seed commands
│ │ ├── Backup*.php # 2 backup commands
│ │ ├── Make*.php # 6 scaffolding commands
│ │ ├── ScheduleRunCommand.php
│ │ ├── DownCommand.php / UpCommand.php
│ │ ├── TestCommand.php / TestE2eCommand.php
│ │ ├── VersionCommand.php
│ │ └── TinkerCommand.php # Interactive REPL
│ ├── Database/ # Base Seeder contract
│ ├── Migration/ # Migration engine (Migrator)
│ ├── Queue/ # Queue engine (QueueManager, Queue)
│ ├── Scheduling/ # Task scheduler (Event, Task)
│ ├── Support/ # FeatureDiscoverer (paths, files, namespaces, classes, composer)
│ └── Traits/ # InteractWithProcessWire
├── resources/
│ └── stubs/ # Scaffolding templates
│ ├── module.stub
│ ├── fieldtype.stub
│ ├── inputfield.stub
│ ├── process.stub
│ ├── pest.stub
│ ├── playwright.config.stub
│ ├── playwright.global-setup.stub
│ ├── playwright.global-teardown.stub
│ ├── playwright.helpers.stub
│ ├── playwright.spec.stub
│ ├── queue.stub
│ ├── seeder.stub
│ ├── task.stub
│ ├── migration.stub # Blank migration
│ ├── migration.create-field.stub # Field creation
│ ├── migration.create-template.stub # Template + fieldgroup
│ ├── migration.attach-field.stub # Field-to-template
│ ├── migration.create-page.stub # Page creation
│ ├── migration.create-role.stub # Role + permissions
│ └── migration.install-module.stub # Module install
└── composer.json
Bootstrap Flow
- Locate Composer autoloader (supports standard and symlinked setups)
- Walk upward to find
wire/core/ProcessWire.php - Boot ProcessWire with database config (graceful fallback if unavailable)
- Register 75 built-in commands
- Auto-discover custom commands dynamically from:
- Site profile:
site/commands/ - Installed modules:
site/modules/*/commands/
- Site profile:
- Discover commands from Composer packages (
extra.processwire-console.commands) - Run the Symfony Console application
Design Principles
- Null-safe: All ProcessWire API
->get()calls are guarded againstnullreturns - Strict typing:
declare(strict_types=1)in every file - Consistent I/O: All commands use
laravel/promptsand standard JSON envelopes ({"ok":true|false,...}) - Dual output: Human-readable tables + machine-readable JSON on every command
- Non-destructive defaults: Confirmations on mutations,
--dry-runfor previews
Requirements
| Dependency | Version |
|---|---|
| PHP | ≥ 8.3 |
| ProcessWire | 3.x |
symfony/console |
^7.0 || ^8.0 |
laravel/prompts |
^0.3 |
dragonmantank/cron-expression |
^3.6 |
License
MIT — see LICENSE for details.