Commands and health check

Fifteen commands cover installation, verification, upkeep and keys. Models are given as a class name or a morph alias, and the commands call the injected SentinelManager, so they also run against Sentinel::fake() in your tests.

php artisan sentinel:verify                                   # every sealable model
php artisan sentinel:verify "App\Models\Invoice" --seal=financial --ledger
php artisan sentinel:verify --fail-on=tampered,missing --fail-on=backlog
php artisan sentinel:verify --ledger --anchor='<json>'           # compare a payload from a log anchor
php artisan sentinel:verify --check-schema --limit=10000         # CI against a staging snapshot
php artisan sentinel:reseal "App\Models\Invoice" --from-key=default-20250901-a1b2c3 --dry-run
php artisan sentinel:seal-missing "App\Models\Invoice" --reason="Initial baseline 2026-10"
php artisan sentinel:inspect "App\Models\Invoice" 42 --seal=financial
php artisan sentinel:prune --dry-run
php artisan sentinel:key:list --ring=http

Options worth knowing

• --fail-on takes VerificationStatus values (tampered, missing, … — also outdated and unsealed, which never fail otherwise) and LedgerFindingKind values, repeated or comma-separated. Naming statuses replaces the default — only those fail; naming only ledger kinds keeps every failing status. Ledger violations always fail; backlog and anchor_unreachable fail only when named. An unknown name exits 2.
• --anchor='<json>' (a payload copied out of a write-only log anchor) is read only together with --ledger; an undecodable payload exits 2.
• --isolated[=EXIT] (sentinel:verify, sentinel:checkpoint) skips the run — exit 0, or the given code — while another instance holds the lock.
• Ranges: --chunk 1–100 000, --limit ≥ 1 (rows in total, across models), --max-findings 0–1 000 000, --batch 1–100 000; reasons 1–sealing.reason_max_length characters, a revoke reason at most 1 000.
• --json: sentinel:verify prints models, unresolved_types, scanned, counts, findings, truncated and a ledger object; sentinel:check prints failed and the list of checks, where failed honours --strict.
• sentinel:inspect keeps values redacted unless --show-values (they may contain personal data); sentinel:key:import reads material from --file or a hidden prompt, never from an argument that would land in shell history. A seal row with a corrupt sealed_at is still shown by sentinel:inspect (sealed at —, status malformed (sealed_at), exit 1) instead of aborting it.
• sentinel:key:reseal walks every ring that stores keys in the database (--ring for one), row by row under the row’s lock, and prints ring:kid → "label" before writing — binding, would bind (--dry-run, which writes nothing) or already bound — with control and invisible characters, < and > escaped like sentinel:key:list’s. It is idempotent, and on success without --dry-run it reminds you to set SENTINEL_REQUIRE_BOUND_LABEL=true.

Exit codes

0 means success, 1 failure and 2 invalid input:

Scheduling

The provider registers the upkeep on the scheduler while schedule.enabled is on (the default), each task withoutOverlapping()->onOneServer(). The full scan defaults to daily — hourly full-table scans are a silent load on large tables — while the checkpoint stays every minute, because its interval is the window in which a rollback goes unseen:

To wire them yourself, set SENTINEL_SCHEDULE=false and add them to routes/console.php. Don’t keep hand-written lines next to the automatic schedule — withoutOverlapping() prevents concurrent runs, not double scheduling.

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('sentinel:checkpoint')->everyMinute()->withoutOverlapping();
Schedule::command('sentinel:verify --ledger')->hourly();
Schedule::command('sentinel:verify --json')->dailyAt('03:00')->emailOutputOnFailure('[email protected]');
Schedule::command('sentinel:prune')->daily();

Sentinel::sealables() lists what sentinel:verify scans when it is given no model: sentinel.models first, then every class with seal rows or ledger entries. With nothing to scan it exits 2, so a misconfiguration never reports green. In CI, sentinel:verify --check-schema --limit=10000 against a staging snapshot fails the pipeline on findings, and sentinel:check --strict fails it on any weakened guarantee.

A host without Sentinel’s tables

A host that gets Sentinel only as another package’s dependency never publishes its config or migrations — yet the schedule is on by default. So each scheduled task skips while none of the tables the configuration needs exists (the list the tables check reads):

• No tables at all: checkpoint, verify and prune stay registered (schedule:list shows them) but never start — schedule:run dispatches ScheduledTaskSkipped for each. Nothing fails, so such a host needs no SENTINEL_SCHEDULE=false.
• Any one table present: the host uses Sentinel’s storage and every task runs as before — a half-migrated install fails as loudly as it always did.
• prune skips only while it would prune a Sentinel table: with a cache store, or a store the host bound, it runs whatever tables exist.
• Cannot tell (a connection that fails, a setting that cannot be read, a store that cannot be built): the task runs and reports the failure itself.
• The look-up happens only for a task that is due, once per schedule:run: one hasTable per needed table until the first is found. Migrating turns the tasks on at the next schedule:run.

The skip is silent on purpose, so the health check is not: while a task skips, the schedule check fails and names it, and php artisan about shows auto (checkpoint, verify, prune skipped: no tables). Commands you run yourself and lines you schedule by hand are never skipped.

The health check

sentinel:check (or Sentinel::check()) reports every misconfiguration that silently weakens the guarantees, in one place. Messages name settings, rings, tables and classes — never key material, key ids or labels:

$report = Sentinel::check();          // HealthReport
$report->failed();                    // any failure (warnings do not fail it)
$report->failures();                  // list<HealthCheck>: name, status, message
$report->warnings();