Forge Cli Laravel Package

Product Decisions This Supports

• Where Forge operations should live: dashboard, CLI, or CI/CD. The package is a working reference model of a terminal-first Forge workflow — list servers and sites, trigger and monitor deployments, pull and update environment variables, manage SSH keys. Use it to frame a concrete decision: which of our recurring infrastructure tasks stay in the Forge web console, which move into scripts our engineers own, and which belong in the pipeline. Right now that decision is often made by default rather than deliberately.
• Build vs. buy vs. wrap. This is a cheap, low-commitment spike to test demand for scriptable provisioning before funding internal tooling. The real comparison is three-way: community CLI (this package), Laravel's official Forge CLI, or direct Forge API calls behind a thin wrapper we own. The package's command surface tells us what "table stakes" looks like for whichever option we choose.
• Requirements discovery for the automation roadmap. If "deploy and manage environment changes from the pipeline" is on the roadmap, this package surfaces the hard requirements early and cheaply: token handling and storage, non-interactive behavior, meaningful exit codes, idempotency, retries, and secret-safe output. The 1.2.0 changelog entry about deployment scripts breaking when a hook already exists is a ready-made example of the idempotency class we must design against — worth citing in any spec we write.
• Developer-experience and onboarding investment. A documented CLI path can cut browser-console hand-offs for new engineers: fewer manual dashboard steps, fewer permission gaps, a repeatable set of commands for common tasks. That gives us a measurable input — time-to-first-deploy, number of console touchpoints per task — for DX and onboarding-time decisions.
• Segment validation for "scriptable-first" users. The package's existence and command coverage confirm a real cohort that prefers terminal and scriptable infrastructure over dashboards. Weigh that segment when scoping internal platform surfaces and admin tooling, and when deciding how much of our platform needs an API/CLI before we call it done.
• Explicitly out of scope: decisions requiring vendor SLAs, security assurance, long-term maintenance commitments, or multi-provider support. One release (April 2021), zero Composer dependents, and no deprecation policy are adoption-risk signals, not a roadmap.

When to Consider This Package

Consider it when all of these hold:

• Your stack is Laravel on Laravel Forge, and Forge is the system of record for servers and sites.
• You are on PHP 8+, and you have verified the exact runtime (8.2/8.3, not just 8.0) against your environment rather than trusting the changelog line.
• The goal is a time-boxed spike — days, not quarters — to prove that CLI-driven Forge operations reduce toil: scripted deploys, bulk environment-variable work, SSH key rotation, or server/site inventories for audit and onboarding docs.
• A single named engineer owns the experiment, can absorb breakage, and keeps it off critical paths and off production write paths until proven.
• You accept pinning the version and, if needed, forking the MIT source. Treat it as a starting point, not a maintained upstream dependency.

Look elsewhere when any of these apply:

• Maintenance risk is unacceptable. One release is a sign of life, not a cadence. There is no roadmap, no deprecation policy, no issue triage, and no dependents — so every issue is ours alone. A pilot can absorb that; a platform dependency cannot.
• A first-party path exists. Laravel publishes an official Forge CLI, and the Forge API is directly callable. Either is the better default beyond a spike: the official CLI carries vendor compatibility expectations, while direct API calls give us full control over retries, paging, auth, and output format.
• Security sign-off is required. A third-party tool holding a Forge API token on developer machines or in CI needs review for token scope, on-disk storage, log redaction, and transit. Version 1.2.0's SSH key commands sharpen this: the tool may touch key material in addition to the token, and there is no security documentation and no maintainer to answer questions.
• You need support, SLAs, or team-wide standardization. Standardizing on a community tool converts a personal convenience into organizational debt.
• Non-Laravel or multi-provider infrastructure is in scope. The abstraction is Forge-specific and will not generalize.

How to Pitch It (Stakeholders)

For executives — the one paragraph. This is a small, MIT-licensed, community-built command-line interface for Laravel Forge. It lets engineers run server and deployment operations from a terminal or a script instead of the Forge web console. Version 1.2.0 is a meaningful sign of life — PHP 8 support, SSH key management, and a fix for a deployment-script bug when a hook already exists — but it is one release, not a track record. This package is not a candidate for production dependency: zero dependents, no maintainer support commitment, no security documentation, and Laravel now ships an official Forge CLI with vendor compatibility guarantees. Recommendation: fund a two-week, single-engineer evaluation using this package as a throwaway prototype to quantify hours saved on deploys and environment-variable sync. If the hypothesis holds, build the durable version on the official Forge CLI or the Forge API directly, and carry over the process discipline — not the code. If it doesn't hold, we've spent two weeks to avoid funding the wrong tool.

For engineering — the framing to agree on. The portable artifact from this exercise is not the binary, it's the pattern: pinned versions, thin wrappers (Makefile targets or scripts we own) around any Forge operation, reads before writes, dry-run-by-default loops over lists, restrictive umask and file redirects for anything touching secrets, and SSH key operations treated as a separate, gated, reviewed workflow — never in CI, never with a broadly-scoped token. The CLI itself is a scaffold we expect to outgrow; a broken command costs about an hour to reimplement as a curl call, so the downside is bounded. What we must not do is let one engineer's globally installed convenience quietly become a team standard — that's how organizational debt gets created without a decision.

The ask: one named owner, a two-week box, a written hypothesis with a success metric (hours saved per engineer per month, console round-trips eliminated), a hard rule that no write command touches production during the pilot, and a decision review at the end: adopt the official CLI, build a thin wrapper on the Forge API, or stop.