A Comprehensive Agent's Guide to Laravel Cloud

This guide is for a coding agent operating Laravel Cloud on someone's behalf with the cloud CLI or the Cloud API. It is what we wish we had been told before our agents provisioned, deployed, investigated and tore down dozens of applications across several organizations.

Most of it is about failure. Laravel Cloud mostly works. The places where it does not are rarely loud: a write lands on the wrong environment, a listing prints a production password, a resource you deleted the app for keeps billing, a success status turns out to mean "delivered". Each of those cost us something. Every rule here is there because one of them happened.

How to read this guide

Read every page before your first write to a Cloud organization. The pages are split for the humans who check this guide, not because the parts are independent. A rule on one page often depends on a fact on another.

• Know your CLI covers versions, flags and non-interactive behaviour. Several of the worst bugs below are fixed in recent releases, so start by finding out which one you have.
• Work in the right organization explains how the CLI chooses an organization when several are authenticated, and how to prove the target before a write.
• Keep credentials out of your context lists every surface we know of that returns a secret in plain text.
• Run commands on Cloud covers command:run and tinker, and how to read their results honestly.
• Configure environments covers what Cloud injects and must never be overridden.
• Provision and deploy covers asynchronous resources, managed queues, required packages and runtime traps.
• Attach a custom domain covers domains on Cloudflare-hosted DNS, where the strategy you cannot change later decides everything.
• Reads that lie lists the fields, statuses and logs that report something other than the truth.
• Attribute cost reconciles the bill and attributes it to applications.
• Hibernation and idle cost explains why apps that should sleep do not.
• Clean up safely finds orphaned resources and deletes them without taking anything live with them.

The rules that matter most

If you remember nothing else:

1. Run cloud --version in the shell you will use. Behaviour differs sharply between releases. Upgrade to v0.6.3 or later before writing to anything.
2. Prove the organization before every write. With more than one token stored, the organization is chosen by the directory you run from. Read it back and compare it with the one you were asked to work in.
3. Pass only identifiers you read back in this session. Never pick an ID from a bare list, and never trust that an unknown ID will produce an error.
4. Always pass --fields with --json. Several listings print credentials. Allowlist the fields you need rather than trying to redact what came back.
5. Read exitCode, never status. command.success means the command was delivered, not that it worked.
6. Never set an environment variable Cloud injects. Database, cache, queue, filesystem and session settings come from Cloud. Overriding them breaks production quietly.
7. Never treat an empty read as proof. Relationship arrays, log windows and status fields are often empty or wrong while the resource is in use.
8. Deleting an application does not delete what it provisioned. Teardown is its own operation, and it needs a manifest.
9. Merging to a push-to-deploy branch is a production deploy. Check before you merge.
10. A custom domain's Cloudflare strategy is fixed when you create it, and the CLI cannot send it. Create the domain through the dashboard or the API, or you get the wrong strategy and a site that fails overnight.
11. Stop when something does not reconcile. An inconclusive check is not a pass.

How current this is

Everything here was observed between June and early October 2026, mostly on CLI v0.5.0 through v0.6.3, and checked against the v0.6.3 source on 4 October 2026. Where a later release fixed a problem, we say which one. Where our own notes contradicted each other, we went with the most recent observation and say so.

Laravel Cloud changes quickly. Its API specification changed by about a thousand lines in a single week while we were writing this. Treat every specific claim here as something to verify cheaply before you rely on it, and run cloud <command> -h rather than trusting a flag you remember. When this guide and the platform disagree, the platform wins and the guide is out of date.

What you need

• The Laravel Cloud CLI, installed with composer global require laravel/cloud-cli, at v0.6.3 or later.
• An API token for each organization you work in, added with cloud auth or cloud auth:token --add.
• The name and ID of the organization you have been asked to work in, from the human who asked. If you do not have them, ask before you do anything that writes.