7.7 Console commands
Run commands from app/ as bin/cake … or through the application container:
docker compose exec app bin/cake <command> --help
Use --help before any mutating command. This page is a task-oriented map; the
command parser is authoritative for arguments and safety confirmations.
Context rules
Commands fall into three execution contexts:
- Platform: use the
platformdatasource and never assume a tenant table. - Fleet: select tenant metadata centrally and enter a fresh tenant scope per target.
- Current tenant: operate on
default; in hosted mode they must be invoked by an allowlisted platform schedule/job or another explicit tenant scope.
A command accepting a record ID but no tenant selector does not discover the
correct kingdom. Do not loop database URLs in shell scripts or point default
at a hosted tenant as a fleet substitute.
Tenant lifecycle and migrations
| Command | Purpose |
|---|---|
platform_health |
Check central platform database availability |
platform_migrate <action> |
Manage the central platform migration track |
tenant provision <slug> |
Create platform metadata, database/role/secrets, migrations/defaults, smoke checks, and optional initial superuser |
tenant migrate --tenant <slug> |
Inspect/migrate one active tenant; add --include-suspended when explicitly needed |
tenant migrate --all --include-suspended --fail-fast |
Managed release fleet migration and verification |
tenant_poc |
Provision and verify a safe two-tenant proof-of-concept environment |
platform admin … |
Bootstrap or recover central platform-admin access |
platform release_check … |
Validate an optional release manifest against schema compatibility contracts |
platform nightly_migration_drill … |
Run the configured non-production migration drill workflow |
tenant migrate requires exactly --tenant or --all. --status is read-only.
--fake and --skip-pre-migration-marker are emergency recovery tools, not
release shortcuts. See Migration lifecycle.
Unified worker, schedules, and jobs
| Command | Purpose |
|---|---|
platform worker run |
One bounded cycle: due schedules, active-tenant queues, then platform jobs |
platform schedule due |
Dispatch a bounded set of due schedules with advisory locks |
platform schedule run <name> |
Run one enabled, allowlisted schedule immediately |
platform jobs run |
Claim and execute bounded central platform jobs |
platform jobs check-alerts |
Evaluate job/schedule alert conditions |
platform jobs prune |
Delete expired terminal jobs and their event records |
platform metrics prune |
Delete expired hourly tenant request aggregates |
platform queues run |
Manual bounded default/tenant/platform queue drain compatibility entrypoint |
The local Docker scheduler repeatedly calls platform worker run when tenancy is
enabled. Current operations do not rely on the retired independent
platform-admin-job-runner or tenant-queue-drain schedules.
Tenant maintenance schedules include workflow-scheduler,
active-window-sync, member-warrantable-sync, and age-up-members. Invoke the
schedule name for managed fan-out; the underlying tenant commands do not accept
a tenant selector.
Backup, restore, and disaster recovery
| Command | Purpose |
|---|---|
tenant backup --tenant <slug> |
Create an encrypted tenant logical JSON backup |
tenant_backups_enqueue |
Enqueue backups due under the global active-tenant policy |
tenant restore … |
Restore an encrypted tenant backup under the suspended/confirmation contract |
tenant restore_drill … |
Plan and record an isolated tenant restore drill |
platform backup |
Create an encrypted PostgreSQL dump of the platform database |
platform backup decrypt … |
Decrypt a platform backup for controlled external DR only |
platform backup-keys ensure |
Reconcile required platform and tenant backup wrapping keys |
platform backups prune |
Remove expired backup objects/metadata under retention policy |
dr_preflight |
Read-only failover/DR health and backup-freshness checks |
platform escrow … |
Record KEK escrow ceremony/verification metadata |
Tenant and platform backup formats are different. Destructive restore/decrypt commands may expose or overwrite sensitive data and require the exact backup and restore runbook, an isolated output path, and explicit approval.
The unnamespaced backup command is the legacy/self-service backup interface.
Do not use it for managed fleet backup or platform database recovery.
Secret operations
| Command | Purpose |
|---|---|
platform secrets import-env |
Import only missing environment-backed secret values into the configured store |
platform backup-keys ensure --allow-read-only |
Verify/reconcile backup keys during deployment readiness |
The import does not overwrite an already rotated database-backed value. Commands must print references/status only, not secret values. Platform admin bootstrap may intentionally reveal one-time credentials in a controlled terminal; never capture that output in CI logs or documentation.
Workflow maintenance
| Command | Purpose |
|---|---|
workflow diff |
Compare repository workflow JSON with published tenant DB versions |
workflow sync |
Publish repository definitions when versions drift |
workflow_scheduler |
Dispatch due workflow schedules in the current tenant |
workflow reconcile_approvals |
Reconcile approval state using the command’s guarded options |
Run workflow diff/sync inside the intended tenant context. Scheduled hosted
execution uses platform schedule run workflow-scheduler. Prefer trigger-driven
reconciliation and reviewed workflow definition versions to direct table edits.
Tenant application maintenance
| Command | Purpose |
|---|---|
generate_public_ids |
Backfill missing public IDs for supported tenant tables |
sync_active_window_statuses |
Workflow-first status reconciliation in the current tenant |
sync_member_warrantable_statuses |
Reconcile member warrant eligibility in the current tenant |
age_up_members |
Workflow-first youth account transition in the current tenant |
image_cache_gc |
Remove stale derived Glide image-cache files |
roles_audit_branch_scope |
Audit branch-scoped role/permission configuration |
telemetry_check |
Validate telemetry configuration and optionally send a smoke trace |
Use each command’s dry-run/status mode where available. age_up_members and
sync_active_window_statuses are documented in Youth age-up
and Active-window synchronization.
Local/reset and compatibility commands
| Command | Status |
|---|---|
reset_database |
destructive local/legacy reset; prefer repository ./dev-reset-db.sh --seed for Docker multi-tenant development |
update_database |
historical upgrade/seed reconciliation used by the controlled local reset path |
advance_dev_seed_dates |
development-only adjustment of date-sensitive seed examples |
migrate_award_events |
compatibility migration from the retired Award Events model to Gatherings |
awards migrate_award_recommendations |
controlled Awards recommendation/workflow migration |
awards materialize_bestowal_todos |
materialize current Awards bestowal follow-up work |
audit_bestowal_links (long alias awards.audit_bestowal_links) |
audit Awards bestowal/recommendation relationships |
awards reconcile_recommendation_state |
compare legacy recommendation state with workflow ownership |
kmp_install |
archived legacy deployment helper; new installations are retired |
These are not routine production scheduler commands. Follow their parser help, owning domain guide, and migration/runbook evidence. Prefer a dry run and backup before compatibility data work.
Adding a command
A new command must declare its context and make unsafe ambiguity impossible:
- platform-only, fleet selector, or current-tenant ownership;
- bounded work, timeout, retry/idempotency, and advisory/concurrency lock;
- dry-run/status mode for risky mutation;
- scrubbed output and central/tenant audit as appropriate;
- non-zero exit on partial failure;
- allowlist registration if scheduled; and
- command, tenant A/B cleanup, and failure tests.
Do not add a cron shell loop for fleet work when platform_schedules and the
unified worker can express it safely.