Forge Cli Laravel Package

Technical Evaluation

Architecture fit

laravel/forge-cli is not a library you embed in an application — it is a Laravel Zero (standalone Symfony Console / Laravel components) binary that wraps the Laravel Forge v2 REST API and layers an SSH client on top of it. The architectural decision it implies is therefore not "which package do we install" but "do we accept Forge as our infrastructure control plane, and do we want to drive it from a terminal/CI rather than the dashboard."

That distinction drives everything a TPM should weigh:

• Value surface is operational, not in-product: provisioning visibility, deploy triggering, log tailing, .env pull/push, SSH configuration, database shell, daemon management.
• It is a thin client. Almost nothing in the tool is logic we would otherwise have to write, but almost nothing in it is logic we can extend either. The CLI owns command parsing, polling, and SSH plumbing; Forge owns the state.
• The real dependency is the Forge API and the Forge account, not the package. The CLI is replaceable in a sprint; migrating off Forge is a platform migration.
• The companion HTTP SDK (laravel/forge-sdk) is the better fit if we need Forge operations inside application code, a custom dashboard, or an internal admin tool. The CLI is the right fit for humans and pipeline steps.

Integration feasibility

High for a Laravel/PHP shop already on Forge; moderate-to-low for anyone else.

• Installation is deliberate: composer global require laravel/forge-cli (or a project require-dev + vendor bin), so it lands in developer machines and CI images, not in production composer.json dependency graphs. This is why dependents: 0 on Packagist is not a red flag — it is the expected shape for a globally installed CLI.
• Authentication is a Forge API token; FORGE_API_TOKEN as an environment variable is explicitly supported for CI (added in v1.3.1), and non-interactive usage was hardened in v1.3.2. This is the single most important integration fact: the tool was designed to be scriptable, not just interactive.
• Deploy polling was made configurable (poll interval and timeout, v2.0.3), which is the difference between a CI step that reliably fails fast and one that hangs a pipeline.
• SSH-dependent commands (ssh, database:shell, log tailing) require a working local SSH identity and correct remote user/port. Custom SSH ports are honored (v1.8.1), and ssh:configure exists, but key distribution remains a human/ops prerequisite.

Technical risk

• API-coupling risk is the dominant risk. v2.0.0 was a hard cut to the Forge v2 API. Any breaking API change on Forge's side surfaces here as a breaking CLI release, and there is no abstraction layer we control. Pinning the CLI version in CI is mandatory.
• Blast radius of token compromise is the account, not the repo. A Forge API token can provision, destroy, and redeploy servers. Treating FORGE_API_TOKEN as a standard CI secret understates it; scope it to a dedicated machine user and rotate it.
• Low community signal. ~246 stars and a modest opportunity score indicate limited third-party adoption and therefore limited public troubleshooting knowledge. Mitigation: the maintainer is the official Laravel org with a funded commercial product behind it, so abandonment risk is lower than the star count suggests, but community support depth will be shallow.
• Version churn in a short window. v2.0.0 → v2.0.4 with several .0.x fixes (deploy log correctness, polling configuration) means early v2 adopters absorbed real bugs. We should not adopt a .0 release.
• Destructive verbs exist. Server/site operations and env:push mutate production. There is no dry-run story documented; process controls (review, branch protection, manual approval gates) must substitute.

Key questions

1. Is Forge our sanctioned infrastructure control plane, or is this an evaluation-only tool? If the former, what is the exit plan?
2. Which commands do we intend to automate in CI versus reserve for human operators, and who approves that list?
3. Do we need in-application Forge operations (→ Forge SDK) in addition to CLI automation, which would mean two integrations to maintain?
4. What is our pinning and upgrade policy for a tool whose major versions follow an external API?
5. How is the Forge API token scoped, stored, and rotated, and which environments may hold it?
6. Does our team have SSH key hygiene sufficient for the SSH-backed commands, or does that become a prerequisite workstream?

Integration Approach

Stack fit

Strong fit if the stack is Laravel/PHP on Forge-managed servers; effectively no fit otherwise.

• Best fit: PHP/Laravel applications deployed to Forge, with GitHub Actions or equivalent CI, where deploy triggering and post-deploy log capture are the desired automation.
• Acceptable fit: teams on Forge that primarily want faster local ergonomics (.env sync, SSH shortcuts, log tailing) without changing deployment architecture.
• Poor fit: non-PHP stacks, non-Forge hosting (Ploy, Envoyer, Kubernetes, plain Ansible), or multi-cloud estates where Forge is one of several providers — the CLI would be an inconsistent one-off.
• Explicitly not a library integration. There is no service provider to register, no facade, no config file in our app. Attempting to require it into application code is an anti-pattern; use the Forge SDK for programmatic needs.

Migration path

Adopt additively; there is no migration, only adoption.

1. Read-only phase. Install globally on one or two engineers' machines. Exercise server:list, site:list, and log-tailing commands against a non-critical Forge account. This validates auth, SSH, and the token model with zero mutation risk.
2. Developer ergonomics phase. Standardize the install in the team's onboarding doc and dotfiles; add ssh:configure guidance. Track whether engineers actually use it — if not, stop here, because the CI case is the only one with measurable ROI.
3. CI shadow phase. Add a deploy step to a single non-production site using a pinned version and FORGE_API_TOKEN from the CI secret store. Run it in parallel with the existing deploy path (or as a manual workflow_dispatch) and compare outcomes.
4. CI primary phase. Promote to the standard deploy path for one application, with an explicit approval gate and a documented rollback (revert to dashboard deploy).
5. Broaden or stop. Expand application-by-application only after the first has run clean for a defined probation period.

Compatibility

• PHP runtime: v2.x requires a modern PHP (the 1.8.0 line declared PHP 8.2 support; the Laravel Zero 10 migration in 1.7.0 set the floor). CI images and developer machines must meet it — check the pinned runner image, since ubuntu-latest drift is a common failure.
• Forge API v2 only. Post-v2.0.0 the CLI will not work against v1 endpoints. Any internal scripts or docs referencing v1 behavior must be retired.
• Non-interactive safety. Interactive prompts can hang headless pipelines; v1.3.2 addressed this and v1.6.0 added a username option required by the API, but every automated invocation should pass explicit flags rather than rely on prompt suppression.
• SSH commands are not portable to environments without an SSH agent and key material; keep SSH-dependent steps out of containerized CI unless keys are provisioned deliberately.

Sequencing

1. Confirm Forge platform decision and token governance (owner, scope, rotation) — blocks everything.
2. Pin the CLI version; select the latest patch in the v2 line, not a .0.
3. Read-only developer trial; collect usage signal.
4. Single-site CI integration with polling interval and timeout configured explicitly.
5. Documentation: command allowlist, approval gates, incident path if a deploy step fails mid-run.
6. Evaluate Forge SDK only if a programmatic need appears — do not sequence it upfront.

Operational Impact

Maintenance

• Low code maintenance, real version maintenance. We write no code, but we own the pin, the upgrade cadence, and the re-validation after each bump. Budget a small, recurring task per CLI major/minor, triggered by Forge API changes rather than by us.
• Two-maintainer model. The upstream project is backed by the official Laravel org with a commercial service dependency — good continuity signal — but the contributor base is narrow. Watch for staleness against the Forge API as the leading indicator, not commit volume.
• Dependabot/Renovate noise is minimal because the tool lives outside the application dependency graph; conversely, this means upgrades are easy to forget. Put the pin in a place that gets reviewed.

Support

• Internal support load is concentrated in auth and SSH. Most failures will be expired/absent FORGE_API_TOKEN, wrong remote user, or missing SSH key — not CLI bugs. A short runbook covering these three covers most tickets.
• External support depth is thin. Low adoption means fewer Stack Overflow answers and fewer blog postmortems. Escalation path is GitHub issues plus Forge's own support, which is a paid-product channel and reasonably responsive.
• Documentation lives off-repo (forge.laravel.com/docs/cli), so repository reading alone is insufficient for onboarding; link the docs explicitly in internal guidance.

Scaling

• Scales fine along the CI dimension. Each pipeline run is an independent API client; there is no shared state or local daemon. Adding applications adds independent steps.
• Forge API rate limits are the ceiling. Parallel deploys, aggressive poll intervals, or many matrix jobs hitting the API concurrently can throttle. The configurable poll interval (v2.0.3) is the knob; set it conservatively and avoid tight loops.
• Human scaling is the weaker axis. Interactive commands are per-engineer, per-machine, and unversioned by nature; they do not compose into team-wide automation. Value compounds only where commands are codified in CI.
• Single-account concentration. Everything operates under one Forge account/token model; there is no multi-tenant or per-team isolation primitive in the CLI. Large orgs will want separate Forge accounts or tokens per team.

Failure modes

Ramp-up

• Time to first useful command: under an hour for a PHP developer with a Forge account and an API token — server:list proves the whole chain.
• Time to trustworthy CI deploy automation: one to two weeks, dominated not by the tool but by token governance, secret scoping, approval-gate design, and a probation period on a non-production site.
• Skill prerequisite is Forge literacy, not CLI literacy. Engineers who do not know what a Forge site, daemon, or deploy script is will not benefit from the CLI; it accelerates existing knowledge rather than teaching the platform.
• Onboarding cost is low and one-time; the durable cost is the recurring discipline of pinning, rotating, and re-validating — which should be assigned to a named owner rather than left implicit.