Commands and health check

Fourteen 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.

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.

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 or key ids:

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