Forge Cli Laravel Package

Technical Evaluation

Architecture fit

• beyondcode/forge-cli is a Laravel Zero console application that wraps the Laravel Forge HTTP API. It is an operator tool, not an application dependency — it does not belong in an application's composer.json, has zero Composer dependents, and introduces no runtime surface into production services. Fit should be judged as "does a terminal-first Forge workflow reduce toil," not "does this library integrate with our codebase."
• The abstraction is Forge-specific and PHP-specific. It fits only where Laravel on Forge is the system of record for servers and sites, and where the team is already comfortable with Composer-global tooling. It will not generalize to multi-provider or non-Laravel infrastructure.
• The realistic architecture role is a reference implementation for scriptable Forge operations: prove the pattern (scripted deploys, env pulls, inventory reads), then re-implement the durable version on the official Forge CLI or direct API calls. The wrapper scripts — not the binary — are the durable asset.

Integration feasibility

• Integration cost is low and well-bounded: composer global require beyondcode/forge-cli:1.2.0, set the Forge API token, confirm forge --help resolves, then run a read-only command (forge servers, forge sites) to validate the token and detect API drift. This is an afternoon-scale spike, not a project.
• There is no published manual. The --help text and the src/ command classes are the contract, which means feasibility assessment requires reading source for every command we intend to rely on and noting which Forge endpoint each hits.
• The highest-value integration is also the simplest: forge env:pull <server> <site> to sync environment variables without a browser round-trip. Lowest-risk, immediately measurable, and it establishes the credential-handling discipline the rest of the integration depends on.

Technical risk

• Abandonment risk is the dominant risk. Last release 2021-04-12, one release, zero dependents, no roadmap, no deprecation policy, no maintainer support commitment. Every defect is ours alone.
• Silent API drift. The wrapper was written against Forge's API as of 2021. Failures can be loud (acceptable) or can silently target the wrong resource (not acceptable). Read commands must be diffed against the dashboard before any write automation is layered on top, and re-diffed after any Forge-side change.
• Write-path defect precedent. The 1.2.0 fix for "deployment script if a hook already exists" indicates earlier versions could mangle an existing deployment script — a production-affecting, idempotency-class defect. There is no test-coverage signal to bound this.
• Privilege concentration. 1.2.0 adds SSH key management with no security documentation: no stated token scope, no log-redaction guarantee, no storage guidance. This is the sharpest edge in the package and should be treated as a separately gated decision.
• Not pipeline-grade. Exit codes and non-interactive behavior are not reliable enough to gate CI or page a human. Anything requiring retries, idempotency, or alerting must call the Forge API or deploy webhooks directly.

Key questions

1. What is the Forge token scope we are willing to issue, and where does the tool persist it on disk?
2. Is the official Laravel Forge CLI a viable substitute for the commands we actually need? If yes, why pilot the community tool at all beyond a spike?
3. Who is the named owner, and what is the time-box and kill criterion?
4. Do we need CI-driven deploys in the next two quarters? If so, the answer is the API, not this tool.
5. Which PHP minor and resolved Symfony Console version are we validating against — not just "PHP 8 support" as a changelog line?
6. What is the maintenance cost of fork-and-own if upstream stays dormant?

Integration Approach

Stack fit

• Requires Laravel on Forge, PHP 8.0+ (verify the actual minor — 8.2/8.3 — not just the 8.0 claim), and Composer global installs on developer workstations. No application-side changes, no service mesh, no deployment topology impact.
• The natural integration seam is a Makefile or thin shell wrapper we own: deploy-staging, env-sync-staging, sites-on-staging. This keeps team habits stable when the underlying command changes or breaks, and makes the eventual swap to the official CLI or direct API a one-file change.

Migration path

• The migration path is the point: dashboard → CLI pilot → official CLI or direct API. The CLI is a throwaway prototype used to quantify hours saved on inventory reads, env sync, and deployment triggers. When the hypothesis is confirmed or rejected, the wrapper targets survive and the implementation underneath is replaced.
• If we need behavior the package does not expose, the realistic path is fork-and-own under MIT: patch the command class, pin the fork, absorb periodic compatibility checks. That decision should be priced before adoption, not discovered mid-quarter.

Compatibility

• Pin the exact version (1.2.0); this is not a moving target and should never float.
• Record the resolved Symfony Console version at install — that is where subtle breakage hides across PHP minors.
• Establish a standing check: diff read-command output against the Forge dashboard before enabling any write verb, and again after any Forge-side change we hear about.

Sequencing

1. Read-only inventory — servers, sites, deployment history. Validate token, confirm no API drift, capture server/site IDs.
2. Env pull — highest-value, lowest-risk workflow. umask 077, redirect to a file, treat output as secrets.
3. Guarded staging deploy — set -euo pipefail, explicit failure messaging, non-production site first. Test the hook-exists scenario against a sandbox before trusting the deploy-script write path.
4. Dry-run bulk loops — iterate server→site lists with echo-by-default and an explicit --apply / APPLY=1 gate.
5. SSH key lifecycle — separate, reviewed, gated workflow. Not part of the deploy pilot. Never in CI, never with a shared/global token, shell history suppressed.

Operational Impact

Maintenance

• Effectively fork-and-own. With one release in 2021 and no cadence, we own compatibility, patches, and any security response. Budget this explicitly: a named owner, a pinned version, and a periodic compatibility review (PHP minor upgrades, Forge API changes).
• Keep the fallback cost visible: the Forge API is directly callable, so a broken command is roughly an hour to reimplement as a curl call — not a crisis. That is the argument for permitting the pilot and the argument against standardizing on it.

Support

• No maintainer support, no security documentation, no collective debugging across dependents. Any issue is ours alone.
• Security review is required before this touches a Forge token on developer machines: token scope minimization, storage location and file permissions, log redaction, transit. The SSH key commands raise the bar further because the tool may touch key material in addition to the API token.
• Do not let it become a shadow standard. One engineer with a global install is personal convenience; a team depending on it is organizational debt. Decide explicitly: owner, time-box, and an exit criterion.

Scaling

• Per-workstation installs do not scale into a team capability. The scaling story is either (a) a small set of wrapper targets in a repo that everyone uses and one person maintains, or (b) replacement by the official Forge CLI / direct API. Looping over lists — servers to sites, acting per site — is where the tool genuinely beats the console, but those loops iterate over destructive verbs and need dry-run defaults and explicit apply gates.
• The tool does not scale to CI as-is: exit codes and prompt behavior are not pipeline-grade, and the hook defect is a textbook idempotency risk we must own ourselves.

Failure modes

• Silent drift — a command targets the wrong resource after a Forge API change. Mitigation: dashboard diffing on reads, before and after any write automation.
• Write-path corruption — deployment script mangling when a hook already exists. Mitigation: sandbox test of the hook-exists case before production trust.
• Unreliable automation signals — exit codes and interactive prompts that break scripts. Mitigation: keep out of CI; wrap defensively with set -euo pipefail and our own failure messaging.
• Secret leakage — env output or key material landing in shared logs, artifacts, or shell history. Mitigation: restrictive umask, file redirection, history suppression, minimal token scope.
• Runtime breakage on PHP/Symfony upgrades — mitigation: pinned version, recorded dependency versions, verify on the actual minor.

Ramp-up

• Roughly half a day per engineer to first productive use, and an afternoon for the initial spike. The learning curve is dominated by discovering how the tool behaves (help text as documentation, source reading for endpoint mapping), not by conceptual complexity.
• The onboarding benefit is real and measurable: fewer dashboard tabs, fewer manual permission steps, a repeatable command set for common tasks. That should be captured as a DX input, not asserted as a benefit.
• Caveat for onboarding: engineers should learn the wrapper targets, not the bare binary. Teaching muscle memory against an unmaintained upstream creates habits that break with the next Forge-side change.

Bottom line for the portfolio: fund a two-week, single-engineer, time-boxed spike using this package as a throwaway prototype to quantify hours saved on inventory, env sync, and guarded staging deploys. Keep SSH key management out of the pilot. If the hypothesis holds, build the durable version on the official Forge CLI or direct Forge API calls. Do not adopt as a production dependency, and do not let it become the team's default path to Forge.