Artisan commands

This reference is for Nexia maintainers who already have authorized access to the private host environment. Core is not distributed to external developers. These host commands are not prerequisites for the public CLI and cloud sandbox; start with the quickstart.

Inspect the installed command signature from the Core root:

task artisan -- help nexia-apps:make-package-resource --no-ansi1

For a first App, follow Create an App Package and Create a Resource. This page is the option reference.

Signature

Core commands are grouped under nexia-apps:, nexia-agent:, nexia-access:, nexia-runtime:, nexia-demo:, and other functional sections. The old nexia: command names have been replaced without aliases; update external scripts when upgrading. App-owned commands use nexia-app-{app-key}:, such as nexia-app-people: and nexia-app-time-absence:. Register signatures and scheduled calls with that same prefix.

Run every command through the container wrapper. Everything after -- is forwarded to php artisan inside the app container:

task artisan -- nexia-apps:doctor-package-app workshop
task artisan -- list nexia-apps --no-ansi
task artisan -- help nexia-apps:doctor-package-app --no-ansi123

PostgreSQL resolves only inside the container, so any command touching the database fails from the host shell. list is the live installed catalog and help <command> is the exact signature and option reference.

Minimal example

Follow Create a Resource for the ordered generate → activate → targeted migration → install procedure. To preview just the Resource files:

task artisan -- nexia-apps:make-package-resource workshop Note --record-owner=legal_entity --label-ko=노트 --dry-run1

Parameters and command catalog

Common Laravel and tenancy commands

These framework and tenancy commands occur throughout Nexia procedures. Use task artisan -- help <command> before reaching for a destructive variant.

Interactive wizard

Every nexia-apps:make-package-* / nexia-resources:make-resource command runs in one of two modes:

• Fully specified. Every required argument and option is on the command line. Nothing is asked; automation and CI calls behave exactly as written.
• Wizard. An interactive shell omits a required value (name, --family=, ...). The command asks for the missing value, then walks every remaining derived value — display name, App key, table prefix, locale labels — with its derived default prefilled, so you confirm or adjust each one before any file is written.

Non-interactive callers never see a prompt: a missing required value fails with the exact flag to re-run with.

$ php artisan nexia-apps:make-package-app
 App name (PascalCase):
 > Workshop

 App family (lower kebab-case):
 > manufacturing

 Display name [Workshop]:
 App key (lower kebab-case) [workshop]:
 Table prefix (lower snake_case) [workshop]:
 ...1234567891011

nexia-apps:make-package-resource extends the same review with the required Korean label, optional Chinese labels, and a final Publish an App Menu entry? confirmation. A missing Chinese label uses the derived English fallback.

nexia-apps:make-package-app {name}

Creates the App Package baseline under packages/{app_key}/. No domain Resource, no host installation.

Normal generation also rejects an occupied packages/<app-key> path, including files and dangling symlinks, even with --dry-run. It does not fill missing files in an existing App. Use --repository-files-only only for the documented repository support files.

nexia-apps:make-package-resource {package} {name}

Adds an App-owned tenant Resource to an existing package. Refuses a package whose API route group lacks app.installed:{app_key}.

Full option table and generated output: Resource contracts.

Host activation

nexia-apps:activate-package-app {package}

Validates every package definition's prerequisite graph, installs the package into the host, then synchronizes Permission and Core Role definitions.

Missing prerequisites, duplicate keys, or cycles stop activation before any host change. Manifest sync runs strictly — an unreachable database fails the command rather than half-completing.

Without --build-assets, restart the running Vite process before it sees a new frontend entry.

nexia-runtime:generate-app-map

Materializes resolved Composer install paths for Vite, translations, Tailwind sources, and listener discovery. It also writes review-only code-loaded catalogs: generated/app-resource-descriptors.json schema 3 includes Resource Reference providers and reverse consumers, while generated/app-public-events.json schema 1 includes public Event contracts and provenance. No arguments. Run it after changing an installed package, frontend entry, Resource descriptor, or public Event declaration; edit the declarations, never the generated JSON.

Contribution and route caches

task artisan -- nexia-runtime:cache-contributions
task artisan -- nexia-runtime:refresh-runtime-caches
task artisan -- nexia-runtime:clear-runtime-caches123

nexia-runtime:cache-contributions builds the complete request-time surface manifest. nexia-runtime:refresh-runtime-caches rebuilds that manifest and the route cache; nexia-runtime:clear-runtime-caches removes both. Normal requests trust the generated manifest and do not scan contribution source.

Tenant lifecycle

nexia-apps:install-dev-app {app}

Installs a development App for one explicitly selected local tenant. The command requires a local console (APP_ENV=local) and --tenant=<tenant ID>. Only this entry point bypasses Central publication/entitlement and package preview restrictions. It changes neither publication nor readiness. Prerequisites, descriptor validation, migrations, initialization and user authorization still apply.

task artisan -- nexia-apps:install-dev-app workshop --tenant="$nexia_tenant" --dry-run
task artisan -- nexia-apps:install-dev-app workshop --tenant="$nexia_tenant" --with-prerequisites12

--dry-run only displays the plan. Rerun this development command for recovery or reactivation. Production uses the normal tenant installer and distribution policy. This is not a procedure for copying development databases or installation state to production.

nexia-apps:reconcile-app-catalog

Registers discovered host packages in the Central distribution catalog. New entries start as third_party / private / draft; existing operator policy is preserved.

task artisan -- nexia-apps:reconcile-app-catalog
task artisan -- nexia-apps:reconcile-app-catalog --check12

--check reports missing registration and metadata drift without writes. --approve-existing approves every newly discovered App as official / public / published for an initial portfolio backfill. Do not use it for development installation or routine deployment. It does not publish existing draft entries. Manage production publication and private tenant entitlements in Central App Catalog.

nexia-apps:install-tenant-app {app}

Normal installation checks publication, entitlement and readiness, then migrates and initializes the App closure. New tenant provisioning prepares only Core tables. Subsequent tenants:migrate runs update Apps with installation history, including disabled Apps. Deactivation preserves tables and data.

Installs a code-loaded App into the current tenant. Validates the full prerequisite graph and prints an ordered install / reactivate / already-active plan.

After changing tenant state it synchronizes the tenant's Permission catalog and Core Role definitions, then runs App initializers. It does not change User authority. Core Shell manifests are not tenant-installable.

To target a specific tenant, wrap it:

nexia_tenant=REPLACE_WITH_TENANT_ID
task artisan -- tenants:run "nexia-apps:install-tenant-app workshop --dry-run" --tenants="$nexia_tenant"12

nexia-apps:repair-tenant-app {app}

Retries initialization for a tenant-installed App and its prerequisites. Use after a failed installation left rows non-operational with failure metadata.

nexia-apps:deactivate-tenant-app {app}

Deactivates an installed App for the current tenant. Refused while dependent Apps remain active.

Validation

nexia-apps:doctor-package-app {package}

The first command to run when something is missing. Emits one OK, WARN, or FAIL row per check.

Checks include package composer name, package namespace, providers, runtime app registration, runtime app metadata, permissions discovered, contribution locations, permission contributors, navigation contributors, frontend entry, frontend entry shape, frontend component registration, translation catalogs, directory baseline files, and permissions. The human table reports valid declaration counts. JSON groups the selected App's Resource Reference providers and consumers, public Events and subscriptions, and data-import recipes, pipelines, and Resource Transfers. These are code-loaded developer facts, not tenant installation or actor-visible runtime results; zero optional declarations are OK, while broken declarations produce WARN or FAIL rows.

nexia-apps:validate-app-compat

Validates installed App Core and SDK version constraints. Needs no database.

nexia-apps:validate-app-frontend-dependencies

Validates App frontend dependencies against the host package graph and the pnpm lock.

nexia-apps:validate-app-descriptors {app?}

Strictly validates public Resource and standalone Event descriptors, Public Event catalog replacements and collisions, exact subscription names and schema versions, plus Process templates, DMN starters, work actions, user-task forms, start bindings, and Approval presets for one App, or every installable App when the argument is omitted. It reports the first invalid descriptor path with the contract violation behind it and exits non-zero. Run it before activation; activation invokes the same gate before translation and permission synchronization, and tenant installation invokes it before writing tenant state.

It then audits author-facing label ambiguity and fails on it as well: two public lifecycle events in one App sharing a labelKey; two resolving to the same text in a shipped locale, unless they belong to different resources that both declare ResourceDescriptor::labelKey; or a payload field reusing its event's labelKey or a sibling's. That audit reads the App's locale catalogs through the installed App map, so an environment that cannot resolve those paths reports the App as unaudited instead of passing it. Ambiguity is not an installation failure — failing the install gate would omit the whole resource contribution from the live catalog, which degrades authoring more than a poorly named label does.

nexia-resources:validate-resource-import-coverage

Compares every installed App with discovered ImportRecipeContribution and ResourceImportPipelineContribution datasets and .nexia/resource-import-coverage.json. It exits non-zero when an App is unclassified, a dataset is duplicated, or the manifest differs from runtime.

nexia-access:validate-presets

Validates code-defined Role Preset permission patterns. No arguments.

nexia-runtime:validate-translations

Validates host and package translation catalogs without writing.

Search operations

These commands act only when Scout uses Typesense. The database Search profile needs neither command.

nexia-search:reindex {resource?} {--tenant=}

Creates a new physical Typesense collection per Resource, backfills every ready tenant into that one collection, and only then atomically moves the stable alias. A failed tenant leaves that Resource's alias on its previous target and the command exits with a failure. Omitting resource processes every allowlisted Resource.

task artisan -- nexia-search:reindex shell.workspace1

--tenant= is not a narrower rebuild: a collection holds every tenant, so rebuilding from one tenant would delete the others from live search. It refreshes that tenant inside the live collection instead and never swaps the alias. When no alias exists yet, the Resource falls back to the full rebuild across every ready tenant.

nexia-search:check-drift {--tenant=}

Compares tenant-database and Typesense document counts without modifying an alias or engine document. It exits non-zero for drift or an engine failure.

Permissions and translations

nexia-access:sync-manifest

Syncs App permission definitions and Core Roles.

nexia-access:sync-permissions

Syncs the system-owned permission catalog and baseline Role templates. Same --dry-run, --all-tenants, --tenant=, --only-central options.

nexia-access:retire-permission {key}

Audits and retires a stale permission while preserving assignments and flagging affected Roles for review.

Translation catalogs

task artisan -- nexia-runtime:cache-translation-catalogs
task artisan -- nexia-runtime:clear-translation-catalog-cache12

nexia-resources:export-types

Regenerates TypeScript contract files from backend PHP enums.

Use --check in CI.

Demo App fixtures

nexia-demo:seed-apps

Adds repeatable App fixtures to the existing initialized demo tenant without resetting its data. The demo fixture key and primary domain must both match. This command does not install Apps.

Reports seeded Apps and skips non-operational Apps. Any skipped App makes the command exit non-zero; already completed seeds remain applied.

Complete Nexia command inventory

This table covers the custom commands registered by the current host. Installed Apps may register more; task artisan -- list --no-ansi is authoritative for the current source folder.

Output or return: Tests and generated artifacts

Package tests are discovered through extra.nexia.test_paths. With no explicit path, the runner executes the Core suite plus every discovered package path:

task test
task test -- packages/workshop/tests/Feature/NoteAuthorizationTest.php12

Run task check before opening a develop to main promotion PR.

Errors

Conventions

Preview generation, activation and installation with --dry-run before applying unfamiliar changes. Repair and deactivation do not support dry-run. Always pass --tenants when wrapping a command for one tenant; omitting it targets every tenant.

Use --force only when deliberately regenerating files. It never permits a record-ownership change; that requires an explicit data migration.

Real usage

The generated packages/workshop/.github/workflows/ci.yml runs the package validation commands against each supported Core version before its package tests:

php artisan nexia-runtime:generate-app-map --no-interaction
php artisan nexia-apps:validate-app-compat --app=workshop --require-declarations --core-version="${{ matrix.core_version }}"
php artisan nexia-apps:validate-app-frontend-dependencies --app=workshop --require-manifests
php scripts/coupling-ratchet.php check workshop1234

Related

• Task commands — container lifecycle, logs, tests, and wrappers
• Resource contracts — the resource generator in full
• Create a Resource — these commands in task order
• Test an App — the readiness checklist they support
• Fix installation errors — diagnosing a failed run