Artisan Commands Reference

This reference covers commands shipped by the host packages in this repository: Core, Admin, and Frontend. Optional packages add their own commands; check their README or run php artisan list capell in the target app.

Install And Upgrade

capell:install

Runs the main install workflow. It can seed default data, run extension install workflows, configure a theme, create users, clear caches, generate sitemaps when a sitemap command is available, and install developer tooling.

php artisan capell:install
php artisan capell:install --demo --url=https://example.test [email protected]
php artisan capell:install --package-mode=custom --packages=capell-app/blog,capell-app/navigation
php artisan capell:install --profile=equidynamics --url=https://equidynamics.test [email protected]

For a non-interactive local or CI install that runs every Composer-installed Capell package and installs AI / Agent Bridge developer tooling:

php artisan capell:install \
  --no-interaction \
  --url="${APP_URL}" \
  [email protected] \
  --all-packages \
  --developer-tooling

Use --no-boost-install when you only want Composer to install Laravel Boost and Capell Agent Bridge without regenerating local Boost guidelines, skills, or MCP files:

php artisan capell:install \
  --no-interaction \
  --url="${APP_URL}" \
  [email protected] \
  --all-packages \
  --developer-tooling \
  --no-boost-install

In non-interactive mode, always pass --url. If the app already has users, pass --user with an existing user ID or email. If the app has no users yet, pass --name, --email, and --password instead.

Option	Use it for
--demo	Seed demo content during install
--plan	Print the install plan and exit without mutation
--fresh / --fresh=force	Refresh the database before installing; force skips confirmation
--profile=	Apply package, theme, demo, language, and site defaults from an install profile
--package-mode=core|all|custom	Choose how extension packages are selected
--packages=	Comma-separated package names for custom installs
--all-packages	Install all composer-installed Capell packages
--theme=	Activate a theme key when themes are available
--remove-installer	Remove capell-app/installer after a successful install
--languages=	Comma-separated demo language codes
--sites=	Comma-separated demo site names
--seed	Run the application database seeder after installing
--no-seed-default-data	Skip default site, language, content type, and page setup
--url=	Site URL, defaulting to APP_URL
--user=	Existing user email or ID used as default author
--name= / --email= / --password=	First user details when the installer creates a user
--role-users	Create example users for common admin roles
--role-user-password=	Password for example role users
--no-side-effects	Show the install flow without running real side effects
--clear-cache	Clear caches without prompting
--generate-sitemap	Run sitemap generation when the command exists
--install-welcome-route	Remove the Laravel welcome home route when present
--developer-tooling	Install Laravel Boost and Capell Agent Bridge developer tooling
--no-boost-install	Install developer tooling packages without running boost:install
--handoff-json=	Write the redacted install outcome and next action as a versioned JSON artifact
--spec=	Path to a site spec providing site, theme.key, and at least one page
--production	Run unattended, force no interaction, and refuse --fresh

Install profiles can live in config/capell-install-profiles.php, config('capell.install_profiles'), or capell-install-profiles.json. Explicit CLI options always win over profile defaults.

Every successful install prints a Capell Install Handoff after the health summary. It records the selected packages, migration/setup/doctor outcomes, safe Admin and public URLs, the first-page state, warnings, and one next action. Pass --handoff-json=storage/app/capell-install-handoff.json when CI or a clean-consumer release check needs the same redacted contract as JSON. The artifact never requires an account connection or telemetry identity submission.

return [
    'equidynamics' => [
        'packages' => ['capell-app/bookings', 'capell-app/seo-suite'],
        'theme' => 'equidynamics',
        'demo' => true,
        'languages' => ['en'],
        'sites' => ['Equidynamics'],
    ],
];

capell:upgrade

Runs the host upgrade flow: migration phase, registered upgrade steps, cache cleanup, and upgrade ledger checks.

php artisan capell:upgrade
php artisan capell:upgrade --dry-run
php artisan capell:upgrade --only-steps --force-step=2026_05_01_example

Option	Use it for
--dry-run	Show the plan without making changes
--force	Skip interactive confirmations
--force-downgrade	Continue when Composer reports an older version than the ledger
--no-clear-cache	Skip cache clearing after upgrade
--caches=	Comma-separated cache list: all, page, config, views
--skip-migrations	Skip migration publishing and running
--skip-steps	Skip registered upgrade steps
--only-migrations	Run only the migration phase
--only-steps	Run only registered upgrade steps
--force-step=*	Re-run a specific step ID

capell:rollback

Rolls back a recorded upgrade step.

php artisan capell:rollback --step=2026_05_01_example --dry-run
php artisan capell:rollback --step=2026_05_01_example --force

Use --dry-run before a real rollback. Use --force only when the impact is already understood.

The fresh-demo shortcut supplies a known administrator ([email protected] / password). With APP_ENV=production, installation refuses those credentials unless --allow-demo-credentials is explicitly supplied. Prefer a unique administrator password; this flag is for an intentional demo only and does not bypass destructive-install confirmation.

Backup And Recovery

capell:backup:create

Creates a manifest-backed database and configured-media snapshot on the private backup disk. Use --database-only to omit media.

php artisan capell:backup:create
php artisan capell:backup:create --database-only

capell:backup:health

Checks configuration, freshness, minimum retention, manifests, artifact sizes, and SHA-256 checksums. --json provides monitoring output; degraded health returns a non-zero exit code.

php artisan capell:backup:health
php artisan capell:backup:health --json

capell:backup:prune

Lists completed snapshots beyond configured retention. The default is a dry run; --force applies deletion beneath the configured backup prefix.

php artisan capell:backup:prune
php artisan capell:backup:prune --force

capell:backup:restore

Restores a manifest-backed snapshot into a new scratch database and optional non-live media target, then runs doctor verification against the restored database. Live database/media targets and occupied media prefixes are rejected.

php artisan capell:backup:restore SNAPSHOT_ID capell_restore_drill \
  --media-disk=restore-scratch \
  --media-prefix=drills/current

See the backup and restore runbook for configuration, scheduling, retention, restore drills, and the deliberate no-in-place boundary.

Extension Lifecycle

capell:make:theme (capell:make-theme alias)

Scaffolds a Capell theme package. Use --local for app-owned client themes that should register runtime views during fresh installs before package install state exists.

php artisan capell:make:theme equidynamics \
  --package=app/equidynamics-theme \
  --name=Equidynamics \
  --local

Option	Use it for
theme	Stable theme key
--package=	Composer package name
--name=	Human-readable theme name
--path=	Parent directory for the package, defaulting to packages
--extends=	Parent theme key, defaulting to default
--local	Generate local runtime registration without installed-state gating

capell:theme:doctor

Runs theme-specific diagnostics for a local or installed theme package.

php artisan capell:theme:doctor equidynamics --path=packages/equidynamics-theme
php artisan capell:theme:doctor equidynamics --json

Option	Use it for
theme	Theme key to inspect
--path=	Theme package path, defaulting to packages/{theme}
--json	Machine-readable diagnostic report

capell:extension-install

Runs install workflows for extension packages that are already present in Composer.

php artisan capell:extension-install
php artisan capell:extension-install capell-app/blog --url=https://example.test --languages=en --sites=Main
php artisan capell:extension-install --all --dry-run

Option	Use it for
extension	Package name to install; omit to choose interactively
--all	Install every extension not already marked installed
--include-installed	Re-run install workflow for an installed extension
--dry-run	Show the install plan without running commands
--url=	Forward a site URL to packages that declare a URL install param
--languages=*	Forward language values to packages that declare language params
--sites=*	Forward site values to packages that declare site params
--user=	Forward a user value to packages that declare a user param
--assets=*	Forward asset values to packages that declare asset params
--param=*	Forward dynamic params as name=value, --name=value, or package-scoped values

capell:extension-uninstall

Uninstalls extension packages that are already installed in Capell.

php artisan capell:extension-uninstall
php artisan capell:extension-uninstall capell-app/blog
php artisan capell:extension-uninstall capell-app/blog --delete-data
php artisan capell:extension-uninstall capell-app/blog --delete-package

Option	Use it for
extension	Package name to uninstall; omit to choose interactively
--all	Uninstall every installed extension
--delete-data	Run the extension’s optional data deletion hook during uninstall
--delete-package	Delete extension data, then remove the Composer package
--dry-run	Show the uninstall plan without running lifecycle or Composer operations

capell:extensions:repair-composer-drift

Repairs extension records where Capell and Composer disagree. The Extensions dashboard only reports this drift; it does not run Composer during a page request.

php artisan capell:extensions:repair-composer-drift vendor/example
php artisan capell:extensions:repair-composer-drift --all
php artisan capell:extensions:repair-composer-drift --all --force

Option	Use it for
package	Repair one Composer-actionable drift record. This explicit repair ignores the all-package gate.
--all	Repair all Composer-actionable drift records when CAPELL_EXTENSIONS_COMPOSER_DRIFT_AUTO_FIX=true
--force	Allow --all repair even when CAPELL_EXTENSIONS_COMPOSER_DRIFT_AUTO_FIX=false

The command stores the latest repair attempt in capell_extensions.metadata using:

Metadata key	Meaning
composer_drift_last_detected_reason	Last drift reason detected for the extension
composer_drift_last_repair_attempted_at	Timestamp of the latest repair attempt
composer_drift_last_repair_status	success, failed, or skipped
composer_drift_last_repair_message	Operator-facing result or failure message

Composer repair is only safe for records where the registry manifest exists and Composer availability or version state is wrong. A stale database record with no current registry manifest, or an extension marked disabled/failed while Composer is present, should be reviewed manually instead of blindly requiring the package.

marketplace:qa:extensions-lifecycle

Runs local Marketplace lifecycle QA for catalogue extensions. Use --dry-run first to confirm scope before running installs.

php artisan marketplace:qa:extensions-lifecycle --dry-run
php artisan marketplace:qa:extensions-lifecycle --dry-run --json
php artisan marketplace:qa:extensions-lifecycle --only=vendor/package
php artisan marketplace:qa:extensions-lifecycle --only=vendor/package --update-from=1.0.0
php artisan marketplace:qa:extensions-lifecycle --skip-delete --stop-on-failure

Option	Use it for
--json	Emit a compact JSON report for CI/local automation
--only=	Limit the run to one Composer package
--update-from=	Install this exact version, then queue its update; requires --only
--skip-delete	Uninstall packages without deleting extension-owned data
--stop-on-failure	Stop after the first failed install, uninstall, or delete operation
--dry-run	Resolve catalogue records and print the plan without changing state

The report includes extension name, Composer package, install result, optional update result, uninstall result, delete result, and failure reason. Non-dry runs queue and execute the Marketplace install attempt locally, then uninstall the installed package and delete extension-owned data unless --skip-delete is set. Passing --update-from installs that exact earlier version and runs the normal queued update before uninstalling it.

capell:extension-audit

Validates a package directory, capell.json, or package directory collection against Capell extension contracts.

php artisan capell:extension-audit packages/example
php artisan capell:extension-audit packages/example/capell.json

capell:package:lint

Checks manifest validity, package naming, version syntax, referenced assets, theme CSS registration, and the shared extension-audit contract. Errors return a failing exit code.

php artisan capell:package:lint packages/example
php artisan capell:package:lint packages

capell:extension-playground

Inspects an extension package or manifest without installing it.

php artisan capell:extension-playground capell-app/blog --path=packages

capell:make:extension (capell:make-extension alias)

Scaffolds a local Capell package and manifest. In interactive mode, the command asks for any missing package name, profile, target directory, and display name. In non-interactive scripts, pass package, --profile, and --path.

php artisan capell:make:extension
php artisan capell:make:extension vendor/example --profile=minimal --path=packages --name="Example Extension"
php artisan capell:make:extension vendor/example-tools --profile=full --path=packages --premium

Developer Makers

capell:make

Lists or runs makers registered in MakerRegistry.

php artisan capell:make --dry-run
php artisan capell:make core.action --name=PublishPage --dry-run

Option	Use it for
maker	Registered maker key
--name=	Primary generated name
--type=	Optional type, schema, or component type
--source=	Optional source schema/component key
--livewire	Generate Livewire files when the maker supports it
--database	Allow database writes when the environment permits them
--dry-run	Preview without writing
--force	Overwrite existing files after warning

Legacy maker wrappers

These commands still exist for scripts and muscle memory:

php artisan capell:make-action CreatePage --data
php artisan capell:make-data PageAuthoringInput
php artisan capell:make-extender HeroFields AfterTitle
php artisan capell:make-schema LandingPage
php artisan capell:make-blueprint LandingPage

Prefer capell:make for new docs and examples because it shows registered makers and supports dry runs.

Package Cache And Published Files

Package cache

php artisan capell:package-cache
php artisan capell:package-cache:clear

Use these after changing installed package metadata, manifests, or local Composer path repositories. The build command also writes role-aware Laravel provider manifests below bootstrap/cache/capell-runtime. See Runtime roles before deploying separate public and authoring processes.

Components

php artisan capell:publish-components
php artisan capell:cache-components
php artisan capell:clear-components-cache

Publishing components is an override path. Prefer package extension points when you only need to add behaviour.

Migrations

php artisan capell:publish-migrations
php artisan capell:publish-migrations --type=settings
php artisan capell:publish-migrations --items=create_sites_table --path=database/migrations
php artisan capell:delete-migrations --all
php artisan capell:delete-migrations vendor/example

Use package install commands for normal installs. Reach for direct migration publishing when building packages or debugging install flow. capell:delete-migrations removes published schema migration files whose basenames match registered package database/migrations directories. Extension uninstall runs the same cleanup for the selected extension automatically.

Admin Commands

capell:admin-install

Installs Admin package requirements and can integrate Capell into a Filament panel.

php artisan capell:admin-install --admin-panel-changes=auto --panel=admin
php artisan capell:admin-install --admin-panel-changes=manual

capell:admin-setup

Runs admin setup and Filament panel integration.

php artisan capell:admin-setup --panel=admin --configurators=auto
php artisan capell:admin-setup --integration-only --preview

Common options:

• --url=, --user=, --languages=, --sites=, and --theme= seed initial admin context.
• --integration-only edits the panel without running the wider setup.
• --skip-panel-integration leaves the Filament panel untouched.
• --configurators=auto discovers configurators automatically.
• --no-colors, --no-widgets, and --no-navigation skip those panel changes.
• --skip-permission-sync skips the permission sync that normally follows admin install.
• --preview shows proposed file changes without writing.
• --force skips confirmation prompts.

See Admin setup for the panel integration flow.

Admin cache and publishing

php artisan capell:admin-clear-cache
php artisan capell:admin-cache-widgets
php artisan capell:admin-clear-widgets-cache
php artisan capell:admin-cache-configurators
php artisan capell:admin-clear-configurators-cache
php artisan capell:admin-publish-resources --type=page --force
php artisan capell:admin-publish-resources --resource=PageResource

Option	Use it for
--type=	Only publish resources of the given type
--resource=	Only publish one resource, by label or class name
--force	Overwrite resource files that already exist

capell:admin-publish-resources is an advanced escape hatch. Most package work should use resources, extenders, configurators, bridges, and settings schemas instead of publishing host resources.

Admin upgrades

php artisan capell:admin-upgrade
php artisan capell:admin-upgrade-summary-email

Upgrade summary email recipients come from CAPELL_UPDATE_NOTIFICATION_EMAILS.

capell:admin-sync-permissions

Re-synchronises Capell’s admin permissions with the roles defined in configuration. Run it after adding an extension that registers permissions, or when an upgrade reports missing permissions.

php artisan capell:admin-sync-permissions
php artisan capell:admin-sync-permissions --mode=upgrade

Option	Use it for
--mode=	install (default) for a first sync, upgrade when reconciling an existing install

Deployment And Maintenance

capell:doctor

Runs Capell’s health checks and reports what is wrong with an installation. This is the first command to run when something is broken, and the last one to run after a deploy.

php artisan capell:doctor
php artisan capell:doctor --json

Option	Use it for
--json	Machine-readable report for monitoring or CI
--install-summary	The installer-focused summary, including package-owned checks
--skip-package-doctors	Skip package-owned doctor commands when building the install summary
--connection=	Verify against an existing database connection instead of the default
--database=	Override that connection’s database name or path for isolated verification
--repair-page-url-domains	Writes data. Creates or restores missing site domains for page URLs before checking

Every option except --repair-page-url-domains is read-only. That one repairs records before reporting, so run the command without it first and read the result before letting it change anything.

Checks cover required tables, the morph map, storage writability, seed data, config files, manifest contracts, installed packages, Vite inputs, generated Tailwind CSS, admin access, the homepage route, the default theme and layout, page URL site domains, runtime tooling, database backup binaries, and whether the cache store can be shared between nodes.

Three of those relate directly to hosting:

Check	Fails when
core.runtime.tooling	proc_open is disabled, or composer/npm are missing — extension installs, package setup, backups, and asset rebuilds depend on them
core.backup.database-binaries	Backups are enabled but mysqldump/pg_dump cannot be found for the active connection
core.cache.shared-store	The cache store is file, array, or null — fine on one server, unsafe behind a load balancer

The last one is a warning by design: single-node installs on the file driver are fully supported. See web server configuration.

capell:health

Runs read-only operational checks with deterministic grouped output and a non-zero exit code for warnings, failures, exceptions, or timeouts. Use --json for monitoring and scheduled execution. Each check runs in an isolated subprocess, so a timed-out check cannot prevent later checks from reporting.

php artisan capell:health
php artisan capell:health --json

Core includes core.disk-capacity. Configure its storage path, minimum free bytes, and timeout with CAPELL_HEALTH_DISK_PATH, CAPELL_HEALTH_MINIMUM_FREE_BYTES, and CAPELL_HEALTH_DISK_TIMEOUT_SECONDS. The default minimum is 1 GiB.

Packages add checks by implementing Capell\Core\Contracts\Health\HealthCheck and tagging the service with HealthCheck::TAG. IDs and categories must be stable lowercase identifiers. Summaries and remediation are sanitized before output; sensitive diagnostic detail belongs in protected application logs.

Laravel owns dispatch policy. Applications may schedule capell:health --json; Core does not register a schedule or choose alert destinations.

capell:runtime-refresh

The single command to run after deploying new code. It refreshes Capell’s deployment caches, warms critical pages, and verifies the result, exiting non-zero if any stage fails — so a bad deploy fails the pipeline instead of surfacing as a broken site.

php artisan capell:runtime-refresh

It runs six stages in order, reporting each as passed, failed, or skipped:

Stage	What it does
Packages	Rebuilds the Capell package cache (capell:package-cache)
Views	Clears compiled Blade views (view:clear)
Config	Refreshes the Laravel configuration cache
Routes	Refreshes the Laravel route cache
Warm	Requests critical runtime pages so the first visitor does not pay for a cold render
Doctor	Runs Capell Doctor and fails the command on a failing check

A stage that throws is caught and recorded as failed rather than aborting the run, so one command reports every problem at once. Prefer this over calling the individual cache commands yourself.

On multi-server hosting, run it on every node — the caches it rebuilds are node-local.

capell:purge-soft-deleted-media

Force-deletes media that has been soft-deleted for longer than the retention window, reclaiming disk space.

php artisan capell:purge-soft-deleted-media --pretend
php artisan capell:purge-soft-deleted-media --days=30

Option	Use it for
--days=	Retention window in days; defaults to 30
--pretend	Report what would be purged without deleting anything

Capell already schedules this daily at 03:00 with withoutOverlapping() and onOneServer(), so you do not need to register it yourself — you only need Laravel’s scheduler running. Use --pretend first if you want to see the effect before trusting the schedule.

capell:marketplace:doctor

Checks the health of queued Marketplace operations. Reach for this first when an extension install is stuck at “queued” in the admin UI — the usual cause is a worker that is not consuming the capell-marketplace queue.

php artisan capell:marketplace:doctor
php artisan capell:marketplace:doctor --json --stale-after=15

Option	Use it for
--json	Machine-readable output for monitoring
--stale-after=	Minutes without a heartbeat before an active operation counts as stuck; defaults to 15

Frontend Commands

php artisan capell:frontend-install
php artisan capell:frontend-install --dev
php artisan capell:frontend-after-install
php artisan capell:frontend-after-install --dev
php artisan capell:frontend-upgrade

--dev runs the Vite development build path instead of the production build where supported.

capell:generate-html

Renders published frontend pages to static HTML files plus a manifest.json, for export — uploading to a CDN or object store, diffing rendered output between deploys, or archiving a site.

This is not the visitor-facing page cache. Artifacts are written to storage/framework/capell-static-artifacts (override with CAPELL_FRONTEND_STATIC_ARTIFACTS_PATH), and nothing in Capell serves them back to visitors — they are output for you to consume. The HTML cache that visitors hit is a separate subsystem owned by capell-app/html-cache.

php artisan capell:generate-html
php artisan capell:generate-html --site=1
php artisan capell:generate-html --url=/ --url=/about

Option	Use it for
--site=	Limit generation to one site ID
--url=	Limit generation to specific public URLs; repeatable

On multi-server hosting the artifacts land on whichever node ran the command. See Web server configuration.

capell:generate-error-pages

Generates the static error page cache for every enabled site, so error responses can be served without booting a full render.

php artisan capell:generate-error-pages

Demo Helpers

php artisan capell:faker --count=25 --packages --sites=Main --languages=en --force
php artisan capell:core-faker --count=10 --sites=Main --languages=en

These create local content for development and testing. Do not run them against production data.

Optional-Package Commands

Commands such as static-site generation, sitemap generation, package-specific demo commands, and frontend Tailwind aggregation are provided by optional packages in a consuming app. Keep those commands in the package README or package docs that own them.

Command	Package
capell:static-site	capell-app/html-cache
capell:xml-sitemap	capell-app/site-discovery
capell:frontend-tailwind-assets	capell-app/frontend
capell:admin-demo	capell-app/demo-kit
capell:demo-kit-full-demo	capell-app/demo-kit

The source of truth in any app is:

php artisan list capell

Further Reading

• Install guide
• Configuration reference
• Admin setup
• Creating Capell packages
• Approved packages