CLI and operations

Clean Framework · DOCUMENTATION

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

Framework console

bin/clean and every application command use the same console kernel. New commands implement TypedCommand; the original Command interface remains as a compatibility adapter for one migration milestone. Typed commands declare:

typed long options and positional arguments;
allowed DEV/TEST/STAGE/PROD environments;
read-only, mutating, or destructive classification;
maximum runtime and batch size;
an optional application-level lock;
safe structured result fields and whether a dry-run is meaningful.

bin/clean is the non-mutating package entry point:

php bin/clean list
php bin/clean version
php bin/clean doctor

The package console reads VERSION and the selected APP_ENV (DEV by default for this read-only package tool); it no longer reports a hard-coded 0.1.0/DEV when an explicit TEST/STAGE/PROD was selected. Application consoles still require their own explicit environment/configuration composition.

Applications may register DebugMetadataCommand('route', $router), DebugMetadataCommand('container', $container) and DebugMetadataCommand('config-schema', $schema). These CLI-only commands deny STAGE/PROD, never resolve controllers/factories, and omit actual config values, schema allowedValues/patterns, handler objects, defaults and closure captures. Developer-owned service names/route patterns must not contain secrets. No hosted diagnostic route is installed. QueueFailedCommand/HealthCheckCommand provide corresponding payload-free queue/health inspection when explicitly bound. See operations/recovery.

Exit codes are 0 success, 1 command/validation failure, 2 usage/unknown command, 3 lock denial, and 4 unavailable in the selected environment. Completed typed commands emit one SUMMARY line with command, environment, mutation class, exit code, and bounded command-specific scalar counts.

Unexpected exceptions receive an opaque reference. STDERR and structured logs contain the reference and exception class but not the exception message, CLI option values, credentials, or database/provider payloads. Deliberately thrown ConsoleException messages are a public-safe operator contract. Options declared sensitive are held as redacted SecretValue objects and must be explicitly revealed at a trusted adapter boundary.

doctor reports environment, PHP version, missing configuration key names, and missing extension names; it never prints secret values. health:check runs explicitly configured, non-destructive readiness probes and reports only name, safe category, and latency. The skeleton includes database readiness, so invoking it requires the intended isolated database configuration.

Application console

skeleton/bin/console demonstrates application-owned command composition and registers database migration commands. Creating the mysqli adapter is lazy, but status/plan/verify/migrate require valid application database configuration when they query the ledger.

migrate:plan and migrate accept one inclusive --to=<id> forward target; they reject unknown or backward targets. migrate:verify detects source/ledger drift without mutation. Non-transactional work is always prominent. PROD mutation additionally requires exact environment confirmation and a token accepted by the application's recent-backup verifier. The skeleton verifier is intentionally fail-closed and must be replaced at composition time.

migrate --dry-run resolves and verifies the plan without acquiring the migration lock, creating the ledger, or running migration SQL. Actual apply accepts bounded --lock-timeout=<seconds> and refuses a pending set larger than the command batch policy before creating/changing the ledger.

FileLockFactory provides optional contained single-host command locks under private storage. Commands that need multi-host ownership must bind a shared CommandLockFactory; a local file lock is not a distributed-lock claim.

Phase 5 adds typed queue:work, queue:retry, queue:failed, queue:prune, schedule:run, and cache:clear classes. They are registered by an application only after it binds its queue tables, handlers, schedules, cache, and worker identity. queue:failed never prints payloads; pruning is explicitly destructive and bounded; schedule:run declares a command lock and is safe to invoke once per minute. Queue and scheduler readiness can be included in the existing health:check through QueueHealthCheck and ScheduleHealthCheck. See QUEUE_AND_SCHEDULER.md.

Run mutating commands only after recording the selected APP_ENV, target host, backup/restore point, and maintenance plan. Do not place a checkpoint token in committed config, logs, or reusable shell history. This extraction did not run a database command against any external system.

Apache 2.4 setup

Use the application public/ directory as the only web root. A minimal vhost shape is:

<VirtualHost *:443>
    ServerName app.example.test
    DocumentRoot /srv/example/public

    <Directory /srv/example/public>
        AllowOverride AuthConfig FileInfo Options
        Require all granted
        Options +FollowSymLinks -Indexes
    </Directory>
</VirtualHost>

This is a shape, not a complete deployable TLS/PHP configuration. Explicitly configure certificates and the chosen app.php PHP >=8.5.11 <8.6.0 handler; never assume Apache knows how to execute PHP. Enable mod_rewrite and mod_headers for the supplied policy; AuthConfig overrides permit Require and CGIPassAuth. Do not place .env, config/, storage/, vendor/, migrations, or private files under another reachable alias. The .htaccess preserves Authorization, serves real public assets, denies non-entry scripts/private paths, and routes every other allowed path to app.php. Review symlink/alias policy on the host. Current candidate scoped Apache2.4.68/FPM/PHP8.5.11 acceptance passes112 local checks; see current profile. Historical PHP8.2 evidence is not current-runtime proof. No installed vhost is modified by the harness; actual host qualification is explicitly deferred and remains separate.

Apache verification on an isolated host:

apachectl -t
curl -i https://app.example.test/health
curl -i https://app.example.test/not-found
curl -i https://app.example.test/.env
curl -i https://app.example.test/assets/example.php

Pass criteria: syntax OK; health 200 JSON; unknown path framework 404; .env and executable asset requests denied/not found; existing static files served without PHP; bearer headers reach middleware. These checks are not proven by the PHP built-in server.

Operational boundaries

Optional command adoption and trusted executeInput() versus authoritative Application::run() invocation are covered in module activation. Typed input and mutation classification do not establish locks, operator authorization or consequential-action approval. Use the application's console with explicit locks and enforce domain/PROD approval inside the use case.

The package supplies worker, scheduler, cache, and health command classes, but does not install a running worker, cron entry, supervisor, live provider probe, or deployment job. bin/clean registers package diagnostics; the skeleton's console registers only its explicitly composed application commands. Inspect php bin/console list in the consuming application rather than assuming every supplied class is registered. Applications own deploy, backup, restore, remote publication, supervision, schedules, and provider-specific probes.

Logs must be outside the web root and must exclude credentials, raw tokens, request bodies, database values, and private content.

See TROUBLESHOOTING.md for local startup, HTTP, asset, configuration, and console diagnostics before investigating a target host.

Editorial provenance

Source: docs/CLI_AND_OPERATIONS.md. Source SHA-256: 84b0f33f645cf9e7dbc5eb2f1580f94ccf7f5f1189914ef7a094c2864cb7be8c.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.