Cloud Cli Laravel Package

Product Decisions This Supports

Build vs. buy for internal platform tooling. This is the vendor's own control surface for Laravel Cloud. Every internal script, deploy wrapper, or admin dashboard we'd write against the Laravel Cloud API is a thing we'd have to maintain, version, and secure. Adopting the first-party CLI turns that into an upgrade-tracking problem instead of a build-and-own problem — a materially cheaper posture unless we need behavior the CLI doesn't expose.

CI/CD architecture and pipeline standardization. LARAVEL_CLOUD_TOKEN env-var auth, non-interactive -n flags, --json output, and repo:config for per-repo defaults together make this a legitimate pipeline primitive rather than a developer convenience. That decision — official CLI in CI vs. bespoke API calls vs. a third-party deploy action — is a roadmap-level call about how every Laravel service we run gets shipped.

Environment provisioning as a repeatable recipe. environment:create, database-cluster:create, cache:create, bucket:create, domain:create, environment:variables (append/set/replace) mean a full environment can be scripted end-to-end. This unlocks preview/ephemeral environments per PR, staging parity, and disaster-recovery drills via database-snapshot:create + database-restore:create (PITR). Decide whether that becomes a product capability (fast, disposable review environments) or stays a manual ops task.

Cost and margin visibility. cloud usage, --detailed, --period=previous, and --environment=<id> give per-app and per-resource spend breakdowns from the terminal. This is the cheapest path to per-customer and per-environment cost attribution and COGS analysis — feed it into FinOps reporting before investing in a billing-data pipeline.

Capability gap analysis against the platform roadmap. The command surface is effectively a public map of what Laravel Cloud considers a first-class resource: apps, environments, instances, DB clusters/schemas/snapshots/restores, caches, buckets and keys, domains, WebSocket clusters and applications, background processes, scheduled/one-off commands, dedicated clusters, IP ranges. Conspicuous by absence: declarative/IaC manifests, Terraform/Pulumi provider, traffic splitting or blue/green controls, team/RBAC/SSO management, audit-log export. Those gaps are roadmap inputs for the platform team — or, if we're a customer, reasons to keep a thin abstraction layer rather than hard-coding CLI calls everywhere.

Developer onboarding as a product metric. cloud ship (guided create-and-deploy), cloud dashboard, cloud browser, and cloud completions are DX investments that shorten time-to-first-deploy. If onboarding time is a KPI, the CLI is a lever — and it's free to adopt.

Incident response and observability runbooks. deploy:monitor, deployment:list, deployment:get, and environment:logs can be wired into on-call playbooks so responders don't need dashboard access to diagnose a bad deploy.

Adoption risk to actively manage: pre-1.0 versioning. The project is shipping fast at v0.5.x. Treat the CLI surface as unstable. Decide now to wrap it in one place — a shared CI image, a Makefile, or a thin internal script layer — so a breaking change is a one-file fix, not a repo-by-repo audit. Also decide on version pinning: the documented install path is git clone + a shell alias, which makes reproducible CI installs awkward despite tagged releases.

Security posture decision. Tokens land in ~/.config/cloud/config.json or, preferably, in the environment with nothing written to disk. Masked token listing with --show-sensitive as an explicit opt-in, and --organization behaving as a check (failing rather than silently using the wrong org) when a token is set, are the right defaults. Decide and document which mode is mandatory for CI vs. laptops, and get the masking behavior into the security review.

When to Consider This Package

Adopt when:

• You are running — or actively evaluating — workloads on Laravel Cloud. This CLI is vendor-locked to that platform; there is no partial-credit use case.
• You want deploy, environment, database, cache, storage, and domain operations automated in CI without writing and maintaining an API client.
• Your engineering org is Laravel/PHP-native and terminal-first; shell completions and repo:config defaults will land well.
• You need cost visibility per application/environment and want it before building a billing integration.
• You want a single place to audit what your team can do to production infrastructure, rather than a sprawl of ad-hoc scripts with ad-hoc credentials.
• Your repos are on GitHub and gh is already authenticated in your environments.

Look elsewhere (or push back) when:

• You are not on Laravel Cloud. Full stop — Forge, Vapor, Ploi, Fly, Railway, or raw AWS/GCP need different tooling. This is not a general deployment CLI.
• You need declarative infrastructure as code with drift detection and GitOps reconciliation. The CLI is imperative and one-shot; there is no state file, no plan/apply, no desired-state guarantee. If IaC is a hard requirement, budget for a Terraform/Pulumi provider or a wrapper that layers idempotency on top.
• gh is a blocker. GitHub CLI is a hard requirement for repo linking and repository detection, and PHP 8.3+ is required. Teams standardized on GitLab or Bitbucket, or on locked-down CI images, will hit friction on day one. Validate this before committing.
• You need programmatic control of team membership, roles, SSO, or audit-log export. No commands exist for these; they stay manual.
• You need a stable, versioned SDK to embed inside a product or internal service. Shelling out to a pre-1.0 CLI from application code is a coupling you'll regret; the REST API is the better integration point there.
• Your environment cannot tolerate a clone-based install. Prefer to wait for a first-class distribution channel (package manager, standalone binary, Composer global) if alias-to-a-cloned-directory is unacceptable in your build images.
• You need multi-tenant fan-out at scale — hundreds of apps or environments. --organization is a single-org selector per invocation, and there's no batch or filter-heavy query surface for fleet-scale operations.

How to Pitch It (Stakeholders)

To executives: Laravel Cloud publishes its own command-line interface for deploying and operating applications on the platform. It costs nothing to adopt and it replaces internal glue scripts we would otherwise build and maintain ourselves. Concretely it buys us three things: faster onboarding (a new service can be created and deployed in one guided command), real CI/CD automation with token-based auth and machine-readable output, and per-application and per-environment cost reporting — which is the cheapest route to understanding what each customer and environment actually costs us. The strategic caveat is that it only applies if we're on Laravel Cloud, and it's still pre-1.0, so we'll adopt it behind a single thin wrapper so upgrades are contained.

To engineering: This is the official Laravel Zero CLI covering the full Laravel Cloud resource model — applications, environments, instances, database clusters/schemas/snapshots/point-in-time restores, caches, object storage buckets and keys, domains and DNS verification, WebSocket clusters, background processes, scheduled and one-off commands, usage/billing, and IP ranges. For our purposes the important properties are: LARAVEL_CLOUD_TOKEN for non-interactive auth with nothing written to disk, -n for fully scriptable runs, --json on most commands for piping into other tools, and repo:config to set per-repo application/environment defaults so deploy commands need no arguments. auth:token is now scriptable and masks tokens to the last four characters by default. Our recommendation: adopt it, but wrap it — pin a version, install it in one shared CI image, and keep every call behind a small internal script layer so the pre-1.0 churn (currently v0.5.x, shipping frequently) never reaches application repos. Known frictions to plan around: PHP 8.3+, a hard dependency on an authenticated GitHub CLI, and no declarative/IaC or RBAC/audit-log commands — if we need those, they're separate work.