php squehub contract:export prints the explicitly declared Application Contract as JSON. Its default is OpenAPI 3.2.1; --format=squehub emits the SqueHub-native versioned artifact, --api-version=<version> selects declared API-version operations, and --pretty indents the JSON. Standard output is reserved for the artifact, so php squehub contract:export > openapi.json works. Errors go to standard error. No file-output option or public documentation route is installed.
php squehub contract:verify performs API verification against the native contract. In development or testing it executes explicitly registered eligible GET, HEAD, and OPTIONS cases; --mutations is required for cases using POST, PUT, PATCH, or DELETE, and for any case marked with mutation(). --static never loads case registrations or runs handlers. Production and other non-development environments are static-only. --format=json emits a deterministic report to stdout, while verification errors cause a nonzero exit status.
php squehub sdk:generate --language=typescript|javascript|php --output=<relative-directory> renders standalone clients from that native contract. Add --api-version=<version> for a selected declared version and --check to fail on stale output without writing files. The command requires explicit public contract operations and does not run controllers. See Client SDK generation.
Use php squehub doctor for a safe deployment inspection (--json for CI) and php squehub infrastructure for configured/selected drivers (--json available). Doctor exits 1 only when checks fail; warnings exit 0. See Health.
The optional local Agent and AI integration adds php squehub agent:status [--json] to inspect effective capability/SDK availability without exposing secrets, and php squehub agent:mcp to start the read-only-by-default MCP STDIO process. agent:mcp reserves stdout for protocol frames, requires the optional PHP MCP SDK, and does not start a remote listener. It is not a shell, a migration runner, or an autonomous plan-apply command.
Run agent:status --json before connecting a host. Its compact JSON includes framework (2.0.0), protocol (stdio, 2025-11-25), mode, an opaque Application fingerprint, all 14 effective capability rows, remote_http: false, and mcp_sdk_available. Granting a scoped create_plan operation changes the mode label to inspection-and-proposal; it does not start MCP or enable apply. See local MCP setup for process configuration and MCP tools and resources for the discovered interface.
The local agent:mcp STDIO process has been exercised with the official mcp/sdk 0.8.1 client on Linux. SqueHub advertises MCP revision 2025-11-25; remote transport is unavailable. See Agent and AI for scope and security limits.
Run php squehub help or its short form php squehub h from the project root to list every available command. php squehub and php squehub list also list commands; add --raw for a compact machine-readable list. php squehub help seed and php squehub seed --help describe one command without executing it. CLI bootstrap does not start a browser Session or connect to a database merely to list commands. The five single-file code generators, the SqueHub Feature Blueprint, and mutating Package commands render shared reviewable change plans. Use --preview to inspect without applying and --yes for deliberate non-interactive application.
Package and Kit installation are source-driven: supply an explicit supported source, inspect the plan, then deliberately apply and enable. package:install accepts a physical local directory or a credential-free HTTPS Git repository whose last path component matches a capitalized Package identity. kit:install accepts a physical local directory only. Neither installer accepts ZIP files, release archive URLs, file:// URLs, or version constraints. The planned squehub/media and squehub/app-starter release ZIP URLs are not current CLI installation commands. A future catalog can point to supported sources without becoming an installation registry.
Manual installation copies .example.env to .env. php squehub key:generate prints a fresh private key; paste its complete base64: value into APP_KEY yourself because that command does not edit .env. Alternatively, optional php squehub setup creates or updates selected configuration after plan review and generates a missing key during apply. Run php squehub doctor to inspect either path. When .env is missing or still has the example values, every php squehub invocation prints a setup notice to stderr. Commands continue to work so you can complete setup; command output on stdout, including doctor --json, remains parseable. See the installation steps for PowerShell and Linux/macOS commands.
The optional frontend commands have been exercised with real Vite, React, and Vue builds and a bounded HMR/proxy smoke on Windows and native Linux. Node remains optional unless a frontend profile is selected. Verify generated assets on the deployment host.
Optional typed application data uses Request, Validator, constructor mapping, and the existing Queue/Event/Notification boundaries. Typed application data adds no CLI command for generating data classes or registering payload aliases; declare those in application PHP and register selected durable types during Application boot.
| Command | Current contract | |||
|---|---|---|---|---|
help, h, list, completion | List commands, show help for one command, and provide shell-completion tools. | |||
setup [--environment=local|development|staging|production] [--database=sqlite|mysql] [--preview] [--yes] | Run optional SqueHub Setup: inspect configuration, review a secret-safe plan, apply deliberately, then verify with Doctor. A missing .env requires explicit choices outside a real interactive terminal. Preview writes nothing and does not run Doctor. --yes confirms only Setup changes. See SqueHub Setup. | |||
doctor, infrastructure | Inspect required/optional health checks or the selected local infrastructure drivers without exposing credentials. Both support --json. `doctor --profile=shared-hosting | single-server | worker | multi-server produces separate [deployment evidence](DeploymentProof.md); optional --probe and web-only --verify-url` require a profile. |
agent:status [--json] | Report this Application's Agent mode, capability inventory, optional MCP SDK availability, served STDIO protocol revision, and no secret values. --json is compact; the default is indented JSON. No MCP process starts. | |||
agent:mcp | Run the optional official-SDK MCP server over local STDIO until input closes. Default capabilities are read-only; scoped grants come from Config/Agent.php. No remote HTTP listener, arbitrary shell, migration, or Package lifecycle action. See Agent and AI integration. | |||
key:generate | Print a fresh 256-bit APP_KEY; the command does not edit .env. | |||
start [host] [port] | Runs PHP's built-in development server with public/ as its document root. Only ordinary files under public/assets/ are served directly; other requests use public/index.php. Without an explicit port, it tries 8000 through 8099 and prints the chosen URL; an unavailable explicit port returns an error. Browser session files use a project-specific directory in the system temporary folder so an inaccessible PHP default session path does not break local requests. | |||
dev [--host=HOST] [--port=PORT] [--queue] [--frontend] [--frontend-port=PORT] | Run SqueHub Dev in the foreground: structured Doctor preflight plus the existing PHP development server. An unspecified PHP port uses the first available 8000–8099; an explicit unavailable port fails. --queue adds an existing persistent Queue worker. --frontend adds the explicitly selected local Vite project; --frontend-port requires it. Scheduler remains separate. start remains independent. See SqueHub Dev. | |||
profile:inspect, profile:apply vite|react|vue [--spa] [--preview] [--yes], profile:remove vite|react|vue [--preview] [--yes] | Inspect or review optional frontend composition. Plans show exact owned paths and configuration hashes. Applying never runs npm; removal blocks on modified owned files and leaves unowned dependencies. See Frontend Profiles. | |||
frontend:status [--probe] [--json], frontend:build | Inspect selected adapter/tool/build states separately or build the selected local Vite project and verify manifest outputs. The ordinary status command makes no network probe; --probe checks only configured loopback. See Frontend Profiles. | |||
studio [--port=PORT] | Start the separate read-only SqueHub Studio inspector on 127.0.0.1 in an explicitly enabled development Application. The default searches 8100–8199; no public host option exists. | |||
route:list | Lists application and package routes without web or database bootstrap. | |||
route:cache, route:clear | Build or remove the private derived route artifact. Dynamic or Closure route actions can block a build while ordinary uncached routing continues. See Framework performance caches. | |||
| `contract:export [--format=openapi | squehub] [--api-version=<version>] [--pretty]` | Loads route declarations and emits deterministic, machine-readable Application Contract or OpenAPI JSON to stdout. It does not open an HTTP documentation endpoint or write a file itself. | ||
| `contract:verify [--static] [--mutations] [--operation=<id>] [--format=text | json] [--strict]` | Checks route/contract declarations and, in a development or testing environment, explicitly registered HTTP cases. Mutating methods and marked cases require --mutations; production runs static checks only. The command never creates a public verification endpoint. | ||
sdk:generate --language=typescript|javascript|php --output=<dir> [--api-version=<version>] [--check] | Generates the selected standalone client from explicit native contract declarations. Its ownership manifest protects unknown files; --check compares without writing. No Node process is needed for generation. | |||
queue:work | Runs the persistent Queue worker. --once, --stop-when-empty, --max-jobs, --max-time, --memory (MB), --timeout, --sleep, --tries, and --backoff bound execution. See Queue, including Windows timeout limits. | |||
queue:restart | Writes this application's graceful worker restart marker; an external supervisor restarts exited workers. | |||
queue:status [--connection=...] [--queue=...] | Shows bounded ready, delayed, and reservation counts plus a connection-wide failed count without reading job payloads. A lease count does not prove a worker is alive. | |||
queue:failed, queue:retry <id>, queue:forget <id>, queue:prune [--hours=168] | List safe failed-job metadata, requeue one retained payload, remove one failed row, or prune old failures. Retry requires the explicit failed-payload migration. Commands accept --connection and never print payloads. | |||
schedule:list, schedule:run | Load .php definitions recursively from Project/Scheduler/ and each package Scheduler/ directory; list definitions or execute due work. See Scheduler. | |||
cache:clear | Clears the configured application data cache namespace, never compiled views or sessions. | |||
config:cache [--preview], config:clear | Preview a reviewed private cache publication, build it explicitly, or remove the artifact. Status and command output never include cached secret values. A clear command can recover a corrupt active artifact. See Framework performance caches. | |||
view:cache | Precompiles supported current .squehub.php Views without rendering template code. Reports compiled, reused, and failed counts; exits unsuccessfully if any source fails compilation. | |||
view:clear | Removes only this Application's SqueHub-owned compiled View artifacts. Safe when empty; unrelated Cache entries and Storage state remain. | |||
migrate:plan [--json] | Inspect migration source through the common Change Plan without opening a database or executing migration PHP. Listed files are candidates, not confirmed pending migrations. | |||
migrate, migrate:rollback, migrate:reset, migrate:status | Operate on the configured database. Confirm the target database before use. | |||
seed [class] [--force] | Runs the root or named Seeder. Production-like environments require --force; see Seeders. | |||
seed:status | Lists matching root Seeder filenames without loading their classes and reports that execution history is not persisted. It does not indicate which Seeders have run. | |||
seed:rollback <class> [--force] | Calls rollback(): void only on a named Seeder implementing App\Plugins\ReversibleSeeder. It has no automatic history or inverse; production-like environments require --force. | |||
package:list, package:inspect <Name> [--type=route|middleware|view|view_namespace|config|service|scheduler] | Read Package state and saved provenance without executing Package PHP. See Contributions. | |||
package:install <source> [--preview] [--yes], package:upgrade <Name> <source> [--preview] [--yes] | Install or replace Package source under Project/Packages. The new source must have the exact Package identity; installation leaves it disabled. Supported source forms and limits are in Packages. | |||
package:enable <Name> [--preview] [--yes], package:disable <Name> [--preview] [--yes], package:remove <Name> [--preview] [--yes] | Review activation or safe owned-source removal. Shared plans show changes, risk, warnings, and conflicts. | |||
package:verify <Name> | Deliberately boot enabled Package code and refresh one contribution snapshot after loading route and Scheduler definitions. Review source first. See Contributions. | |||
kit:list, kit:inspect <Name> | Inspect discovered Kit manifests, state, declared Package requirements, hooks, and owned-file counts without executing Kit entry PHP. See SqueHub Kits. | |||
kit:install <source> [--preview] [--yes] | Acquire a Kit definition from a local directory after review; installation leaves it disabled and does not publish its application composition. | |||
kit:enable <Name> [--preview] [--yes], kit:disable <Name> [--preview] [--yes] | Review Kit activation and Package requirements. Disable retains published application files and does not cascade Package changes. | |||
kit:upgrade <Name> <source> [--preview] [--yes], kit:remove <Name> [--preview] [--yes] | Review ownership and current file fingerprints before replacing or removing managed Kit definition and published files. Upgrade uses a local directory source. Modified or unowned files block unsafe changes, and Kit-owned Migration replacement/deletion is blocked. | |||
bundle:export <destination>, bundle:inspect <archive> [--json] | Export a bounded portable project source bundle to a new file, or verify its entire manifest and payload without extraction. The bundle excludes .env, live records, runtime Storage, and dependency installations. | |||
bundle:import <archive> <target> [--preview] [--yes] | Review a Change Plan for source import; --preview writes nothing. Interactive approval or explicit --yes is required to apply. It does not execute imported PHP, Composer, migrations, Seeders, or Kit hooks. | |||
upgrade:check <target> [--json] | Compare this application with an explicit local target source directory using static upgrade preflight. It reports compatible, review, blocked, or unknown without applying any change. | |||
| `recovery:plan [--source-bundle=<archive>] [--database-snapshot=<file>] [--snapshot-driver=sqlite | mysql] [--json]` | Inspect recovery boundaries and fingerprint only operator-supplied artifacts. It does not take a database snapshot or restore data. | ||
backup:dev | Creates Storage/Backups/Dev/*.zip with Project/, Config/, Database/, and optional .env and legacy config.php. Requires the PHP CLI zip extension. It omits Assets/, Composer metadata, live database records, and runtime uploads; it is not a production backup or the portable source-bundle tool. Store the archive privately because it can include .env. See Backup and portability. | |||
make:controller, make:middleware, make:migration, make:model, make:seeder | Plan one canonical application file after path and collision checks; each accepts --preview and --yes. Controller, Model and Middleware also accept --package=<ExistingPackage>. Migration and Seeder generation is root-only. See Generators. | |||
make:feature <Name> [--table=<table>] [--route=<path>] [--package=<ExistingPackage>] [--preview] [--yes] | Plan a Model, Migration, Controller, Validation rules class, API Resource, one GET route, and runnable test together. The GET scaffold returns a fixed first Page of 20 records with the existing Resource data/meta envelope; applications add validated page selection later. The default singular table and path can be explicitly overridden. Package classes/routes remain Package-local while runnable Migration/test files use root discovery paths. Output says Migration execution: NOT INCLUDED and Seeder execution: NOT INCLUDED; neither runs. See Feature Blueprints. |
Use php squehub route:list for a safe route smoke test. A cache clear is destructive for its selected namespace: in tests and readiness checks set CACHE_DRIVER=array or a disposable cache path. Do not run migrations, Seeders, package removal, or backup creation against an unintended project/database merely as a smoke test.
The command launcher is squehub, with the standard lowercase filename required by its CLI convention. The framework source under App/Clis keeps canonical capitalized names. New Packages use Project/Packages/<PackageName> and Kits use Project/Kits/<KitName> with exact identity casing. Kit lifecycle commands are the only normal entry to Kit hook execution; help, kit:list, kit:inspect, and doctor do not run Kit PHP. php squehub help includes every registered command.
The CLI identifies its framework version as 2.0.0. Check the installed package or Git ref separately when determining whether a particular checkout came from a published release.
Application-facing Plugins import
Application code may import App\Plugins\Seeder, App\Plugins\ServiceProvider, and App\Plugins\Schedule. These entries delegate to the current subsystem; canonical imports and global helpers remain supported. See Plugins for the complete mapping and compatibility rules.