Cloud Cli Laravel Package

Getting Started

The Cloud CLI is not a Composer dependency you require into a Laravel app — it is a standalone Laravel Zero binary you clone once and alias globally. Treat it as a workstation-level tool, like gh or aws.

One-time install (per machine):

gh repo clone laravel/cloud-cli ~/tools/cloud-cli
cd ~/tools/cloud-cli
composer install

# Zsh
echo 'alias cloud="php '$HOME'/tools/cloud-cli/cloud"' >> ~/.zshrc && source ~/.zshrc

Prerequisites beyond PHP 8.3+ and Composer: an authenticated gh (repo linking and GitHub API calls) and git on PATH. Missing gh auth is the single most common first-run failure — check it before you start debugging the CLI itself.

First three commands, in this order:

cloud auth                  # browser OAuth; token lands in ~/.config/cloud/config.json
cloud repo:config           # bind this Git repo to an application + environment
cloud ship                  # guided create-and-deploy flow

cloud repo:config is the highest-leverage step. It writes the application/environment defaults for the current repository, after which cloud deploy, cloud dashboard, cloud browser, cloud environment:logs, and friends stop prompting you for context. Run it from the project root, once per repository.

A good first real use case after that: cloud deploy && cloud deploy:monitor as a single alias, replacing the dashboard click-path for "push this branch."

Implementation Patterns

Repo-scoped defaults (the core ergonomic win). Every command that accepts an application/environment will infer it from repo config when run interactively. Keep commands short in day-to-day use and let the CLI fill in the rest:

cloud deploy
cloud environment:logs
cloud database:list
cloud usage --detailed

Non-interactive / CI usage. Anywhere the CLI might prompt, pass -n and supply context as arguments. Combine with LARAVEL_CLOUD_TOKEN so no config file exists on the runner:

# GitHub Actions
- name: Deploy
  env:
    LARAVEL_CLOUD_TOKEN: ${{ secrets.LARAVEL_CLOUD_TOKEN }}
  run: php path/to/cloud deploy my-app -n

LARAVEL_CLOUD_TOKEN takes precedence over ~/.config/cloud/config.json and writes nothing to disk. Because the token carries its own organization, --organization acts as an assertion rather than a selector — naming the wrong org fails loudly instead of deploying into it. That is the behaviour you want in CI.

Per-command env override trick. An empty value counts as unset, so you can neutralize a saved token for one invocation without unsetting it in your shell:

LARAVEL_CLOUD_TOKEN= cloud application:list -n   # falls back to config file

Scripting via --json. The JSON flag is the difference between a human tool and a building block. Pipe into jq for IDs and status checks:

cloud application:list --json | jq -r '.[] | "\(.id)\t\(.name)"'
cloud deployment:list --json | jq -r '.[0].status'
cloud environment:get --json | jq -r '.variables.FOO'

Wrap these in small shell functions rather than memorizing IDs.

Environment variables without the dashboard. cloud environment:variables supports append, set, and replace modes — the distinction matters: append/set are safe for rotation scripts, replace will drop anything not in your payload. Use set in scripts that push one secret; use replace only when you own the whole variable set and can regenerate it.

One-off command execution. cloud command:run executes against an environment, which covers migrations, backfills, and cache warmups from a deploy script without SSH:

cloud deploy -n && cloud command:run "php artisan migrate --force" -n

Data workflows. The database family is the most operationally useful area: database:open for a local connection to a Cloud database, database-snapshot:create before a risky migration, and database-restore:create for snapshot or point-in-time recovery. A defensible pre-migration habit:

cloud database-snapshot:create -n
cloud deploy -n

Cost awareness in the loop. cloud usage --period=previous and usage --environment=<id> let you diff spend per environment, which is handy for confirming that a torn-down preview environment actually stopped costing money.

Shell completions. cloud completions once, then tab-complete resource names instead of pasting IDs. Underrated given the ~90 command surface.

Gotchas and Tips

It's a clone, not a PHAR (for now). There is no composer global require. Your alias points at an absolute path into the cloned repo, so git pull inside that directory is your update mechanism, and moving the folder silently breaks the alias. Consider putting the alias behind a function that resolves the path.

Version pinning matters at v0.5.x. Pre-1.0 with 52 stars and effectively zero dependents means command names and flags can shift between minor releases. If you wire the CLI into CI, pin the CI checkout to a tag and bump deliberately. Note the v0.5.2 fix for a self-update 404 — self-update is worth validating after any pin bump rather than assuming it works.

Interactive prompts hang non-interactive runs. Any command that can prompt will block a CI job with no TTY. The rule: always -n, and always provide the application argument when the repo config is absent. repo:config is likewise required to be explicit with -n when more than one application exists — otherwise it errors rather than guessing.

Token handling in the process list. cloud auth:token --add --token=... leaks to ps on shared machines. Prefer the pipe form:

echo "$LARAVEL_CLOUD_TOKEN" | cloud auth:token --add -n

Use auth:token --list to see where each token came from (it names the source), and remember output is masked to the last four characters unless you add --show-sensitive.

Multi-org confusion. The saved config file supports tokens for several organizations; the env var does not — a single LARAVEL_CLOUD_TOKEN pins you to one org, and --organization becomes a validation check. If you juggle orgs locally, use repo:config my-app --organization=acme -n per repo and let the config file hold the tokens.

Config location is fixed. ~/.config/cloud/config.json is the documented path. Do not assume it honors arbitrary XDG overrides, and do not commit anything derived from it. On ephemeral CI runners, prefer the env var over writing this file at all.

Diagnosing failures, in order: (1) gh auth status, (2) cloud auth:token --list -n to confirm which credential is in play, (3) re-run with --json to see the raw API error instead of the formatted message, (4) verify you're in the right repo root so repo:config resolves to the app you think it does — running cloud deploy from a nested directory is a classic silent wrong-target.

Extension point: fork it. It's a Laravel Zero app; the source is a normal Laravel project with commands under the app namespace and Pest/Pint/PHPStan configured. If your team needs a bespoke command ("promote staging to production"), adding it here and pointing your alias at the fork is more maintainable than shell-wrapping twenty existing commands. Run ./vendor/bin/pint --dirty and ./vendor/bin/pest before you push.

Don't reach for it for everything. cloud browser and cloud dashboard are escape hatches by design — for exploratory work, one-off log reading, and anything you can't yet name precisely, the dashboard is faster. The CLI earns its keep in repeatable flows: deploy, snapshot, restore, variable rotation, usage checks, and CI.