Auto Shell Laravel Package

Product Decisions This Supports

• Feature: first-class CLI for the product — AutoShell is a convention-over-configuration CLI router. Dropping a class into a recognized namespace registers a command automatically, so a team can ship internal commands (ops tasks, data backfills, maintenance jobs, admin actions) without hand-maintaining a command registry or wiring argument parsing by hand.
• Roadmap: standardize internal tooling before investing in a framework — If the roadmap calls for "CLI parity" across services or teams, this package provides a small, opinionated foundation now, deferring the heavier commitment to Symfony Console or a framework-native runner. That buys optionality: the team can start shipping commands this sprint while the longer-term tooling decision is still open.
• Build vs. buy on a narrow surface — For small-to-medium command surfaces, this replaces "write our own router + argv parser + help generator" with a ~zero-dependency MIT library. The build alternative is real engineering time; the buy alternative is near-zero cost and reversible.
• Use cases it fits: developer/ops tooling, scheduled or cron-triggered entrypoints, one-shot scripts that deserve a help page, internal admin commands, scaffolding generators, and prototypes where speed of adding a command is the primary metric.
• Architecture alignment decisions — The Console→Shell→Exec→Command mapping mirrors Front Controller→Router→Route→Action. Teams already using ADR/MVC get a familiar mental model, which lowers the training cost of introducing a CLI layer.
• DI strategy decision — The pluggable command factory (e.g., PSR-11 container) means the PM can approve "commands get real dependencies" as an accepted requirement, not a rewrite.

When to Consider This Package

Adopt when most of the following hold:

• You have a PSR-4 PHP codebase, a modest CLI surface, and want commands auto-discovered with minimal boilerplate.
• You are convention-tolerant — the team is comfortable with namespace/suffix/method conventions, PHP attributes, and reflection-driven parsing.
• Zero dependencies and small surface area are explicit requirements (constrained environments, supply-chain caution, or desire to avoid pulling in a console framework for a few commands).
• You need typed arguments and options (int/float/string/bool/mixed/array, variadics, short/long options, repeatable options) and generated help/man pages without building that layer.
• You need dependency injection in commands and are willing to supply a PSR-11-based factory — this is supported, so it is not a blocker.
• You are prepared to own the edge cases and contribute fixes upstream; the library is intentionally low-maintenance.

Look elsewhere when:

• The CLI is product-facing or large-surface: you need interactive prompts, progress bars, rich output formatting, table rendering, command testing harnesses, or a broad plugin ecosystem. Symfony Console / Laravel Artisan are the safer defaults.
• Ecosystem and support risk matter: 51 stars and 0 dependents signal a small community and thin third-party validation. Enterprise procurement, an SLA, or a named maintainer commitment are unlikely. Treat bus factor as a real risk and document a migration path.
• You need a framework-native experience — in a Laravel app, Artisan is already there; adding a parallel CLI router creates two idioms.
• The team would have to invent conventions from scratch and has no appetite for that governance overhead.
• Verification note: the recorded last release is dated 2026-03-10; confirm actual release cadence and changelog activity before committing, since a stale or single-maintainer project changes the risk calculus.

How to Pitch It (Stakeholders)

To executives: This is an MIT-licensed, zero-dependency PHP library that lets engineers add CLI commands by writing a class, not by wiring plumbing. It is low cost, reversible, and reduces the engineering time spent on internal tooling and operational scripts. The risk is ecosystem maturity rather than technology: it is a small, single-maintainer project, so I recommend a time-boxed pilot on one internal CLI surface rather than a company-wide mandate.

To engineering leads: The API is deliberately small — Console, Shell, Exec, Command — with reflection-based argument/option parsing, typed casting, attribute-driven help, composable option sets, and a pluggable command factory for PSR-11 dependency injection. It follows PDS conventions and mirrors ADR, so it will read as familiar. The trade-offs are explicit: no interactive prompt layer, no progress/formatting toolkit, no testing harness, and a small community. If the pilot shows we need those, Symfony Console is the documented fallback and the migration is contained because our commands stay plain PHP classes.

Recommended decision: Approve a one-sprint pilot on a single internal CLI surface. Success criteria: measurable reduction in time-to-add-a-command versus our current approach, no blocking gap in argument parsing, option handling, or DI, and a working commands-as-plain-classes pattern that keeps a Symfony Console migration cheap. If the pilot clears those bars, standardize; if not, we have lost one sprint and gained a clear build-vs-adopt answer.