Skip to main content
The Laravel Cloud CLI lets you deploy and manage your Laravel Cloud applications, environments, and resources from your terminal or a CI/CD pipeline.

​
Requirements

  • PHP 8.3 or higher
  • Composer
  • Git
The GitHub CLI (gh) or the GitLab CLI (glab) is optional. When your project doesn’t have a Git remote yet, the ship and deploy commands can use either one, if you’re signed in, to create the repository for you. This is only available when running interactively. The CLI can’t create Bitbucket repositories, so if you use Bitbucket, create the repository yourself and add it as a remote before shipping.

​
Installation

Install the CLI globally:
Note: Make sure your global vendor binaries directory is in your $PATH environment variable, you can read more about this in the Composer documentation.

​
Shell completions

The CLI supports tab completions for Bash, Zsh, and Fish. To generate and install completions for your shell, run:
You can also target a specific shell directly:

​
Authentication

Before using the CLI, you need to authenticate with your Laravel Cloud account. You can authenticate through your browser, provide an API token through an environment variable, or save API tokens on your machine.

​
Browser authentication

The simplest way to authenticate is through your browser:
This command opens your default browser, prompts you to authorize the CLI, and stores the resulting API token locally. The token is saved in ~/.config/cloud/config.json.

​
Token authentication

In CI/CD pipelines and other environments without a browser, provide an API token through the LARAVEL_CLOUD_TOKEN environment variable:
When LARAVEL_CLOUD_TOKEN is set, it takes precedence over any tokens saved in ~/.config/cloud/config.json, and the CLI writes nothing to disk. An empty value counts as unset, so you can bypass the variable for a single command without unsetting it:

​
Saving tokens

On a machine you return to, or when you need tokens for several organizations, you may save tokens to ~/.config/cloud/config.json using the auth:token command. You can pass the token using the --token option or pipe it to the command:
Piping the token keeps it out of your shell history and out of the process list. The --remove option accepts a token in the same way:
To list your tokens, along with the organization each one belongs to and where it was loaded from:
Listed tokens are masked to their last four characters. Pass --show-sensitive to print them in full. If you have saved tokens for multiple organizations, the CLI prompts you to select an organization when running commands. In non-interactive environments, set a default organization for your repository using cloud repo:config --organization instead. When LARAVEL_CLOUD_TOKEN is set, the --organization option becomes a check rather than a choice: repo:config fails if the token doesn’t belong to the organization you named.

​
Quick start

The fastest way to get an application running on Laravel Cloud is the ship command. From inside your project directory, run:
This guided flow walks you through creating an application, configuring your environment, and deploying — all in a single command. It detects your repository, prompts for a region and application name, and optionally syncs your .env variables, creates databases or caches, and configures features like the scheduler, Octane, or WebSockets. You may skip some of the prompts by passing options to the ship command:
The following options are available: Each application belongs to a repository and a root directory. If an application already exists for the same repository and root directory, ship offers to deploy it instead. When running non-interactively, ship stops and prints the ID of the existing application, which you may pass to cloud deploy.

​
Deploying

To deploy your application, run the deploy command from your project directory:
The CLI resolves the target application and environment automatically using your repository configuration. After the deployment starts, the CLI monitors its progress and reports the result in real time. To open your application in the browser after a successful deployment:
To start a deployment and return immediately without waiting for it to finish, use the --no-wait option. The CLI prints the deployment ID so you can check on it later:
You can also monitor an active deployment separately:
If you run deploy non-interactively in a repository that doesn’t have a Laravel Cloud application yet, the CLI runs ship to create one. When running interactively, it asks before doing so.

​
Deployment history

To list an environment’s deployments, view a deployment’s details, or view a deployment’s build and deploy logs:
The deployment:logs command shows each build and deploy step with its status, duration, and output, so you can see which step caused a failed deployment and why.

​
Repository configuration

To avoid specifying your application and organization on every command, you can save defaults for your repository:
This creates a .cloud/config.json file in your project root that stores the application_id and organization_id. Subsequent commands will use these defaults automatically.

​
Managing resources

The CLI provides full CRUD operations for Laravel Cloud resources. Command examples below show the most common operations.

​
Applications

​
Environments

To update environment variables interactively or by using command options:
To view environment logs:
To change an environment’s laravel.cloud subdomain, pass only the first part of the domain. For example, --name=my-app gives my-app.laravel.cloud. The previous domain stops working right away, but the new domain only takes effect on the next deployment, so pass --deploy to deploy the environment right away. You can change the domain once every 30 minutes. When running non-interactively, the command requires the --force option:
To purge the environment’s edge cache, run environment:purge-edge-cache. By default, everything cached at the edge is purged. To purge a single path, every path under a prefix, or a Cache-Tag value, use the --path, --prefix, or --tag option. Purging by tag requires a dedicated edge network:
To list the secrets attached to an environment, or attach secrets to it:

​
Instances

​
Databases

You can manage individual databases within a cluster:
To open a database in your local database client:
Database snapshots and restores are also available:

​
Caches

​
Object storage

Bucket keys can be managed separately:

​
Domains

​
WebSockets

WebSocket applications within a cluster:

​
Background processes

​
Managed queues

Managed queues are a special kind of instance, so these commands accept an instance ID. If you don’t pass one, the CLI prompts you to select a queue:
The managed-queue:create command accepts the --name, --size, --max-workers, --visibility-timeout, --polling-interval, and --shutdown-timeout options, so you can create a queue non-interactively. To list, retry, or delete a managed queue’s failed jobs:
The pause, purge, and delete-failed-job commands accept the --force option to skip the confirmation prompt.

​
Secrets

Secrets are encrypted values shared across your organization that can be attached to environments:
The secret:create and secret:update commands read the secret’s value from STDIN when the --value option isn’t given, which keeps the value out of your shell history:
Values are encrypted on your machine before they are sent to Laravel Cloud, using PHP’s sodium extension. Some Linux distributions ship this extension as a separate package.

​
Commands

To run a one-off command on an environment:
To list previously executed commands:

​
Tinker

The tinker command opens an interactive PHP REPL connected to your Laravel Cloud environment, allowing you to execute PHP code directly against your running application:
By default, a multi-line text input is presented in your terminal where you can type and submit PHP code. Each submission is sent to your Cloud environment for execution, and the result is displayed in your terminal. The session remains open so you can continue executing code.

​
Editor mode

If you prefer to write code in your editor, use the --editor option:
This opens a temporary file in your editor. Every time you save the file, the code is automatically sent to your Cloud environment for execution and the result is displayed in your terminal. The session ends when you close the file. Common editor values include code, subl, vim, and phpstorm. If no value is given, the VISUAL or EDITOR environment variable is used.

​
Non-interactive mode

To execute a single snippet of PHP code without entering the interactive session, use the --code option:
This is useful for scripting and CI/CD pipelines.

​
Timeout

By default, code execution will time out after 60 seconds. You can adjust this with the --timeout option:

​
Metrics and usage

To view metrics for an environment, database cluster, cache, WebSocket cluster, or WebSocket application:
Metrics cover the past 24 hours by default. Use the --period option to choose 6h, 24h, 3d, 7d, or 30d:
To view your organization’s usage and billing summary for the current billing period:
Pass --detailed for a full breakdown by application, resource, and add-on, --environment to filter usage by environment, or --period to view a different billing period. The --period option accepts current, previous, 1, 2, or 3:

​
Utility commands

Open your application in the Laravel Cloud dashboard:
Open your application in the browser:
Retrieve Laravel Cloud IP addresses by region:
List your organization’s dedicated clusters:

​
Agent skills

The CLI can install Laravel Cloud skills for your AI coding agents. Skills are fetched from the laravel/agent-skills repository and installed into the appropriate directory for each agent.
The command auto-detects which agents you have configured and prompts you to select which ones to install skills for. Supported agents include Claude, Cursor, Junie, GitHub Copilot, and a generic agent format.

​
Global vs. project installation

By default, skills are installed to the current project if the Cloud CLI is installed as one of its Composer dependencies, and globally otherwise. You can override this behavior:

​
Specifying agents

To install skills for specific agents without being prompted:

​
Overwriting existing skills

If skills have already been installed, use the --force flag to overwrite them:

​
JSON output

Many commands support a --json flag for machine-readable output, which is useful for automation and CI/CD pipelines:
JSON output is written to STDOUT, and errors are written to STDERR, so you can pipe the output to tools like jq without filtering out error messages. Sensitive values, such as environment variables, database and cache passwords, bucket secret keys, WebSocket application secrets, and API tokens, are masked by default. Pass --show-sensitive to reveal them:
Passing --json also disables interactive prompts. In non-interactive environments, such as GitHub Actions and other CI services, prompts are disabled and output is formatted as JSON automatically. Destructive commands, such as environment:delete, require the --force option when run without a terminal, so they never run without your explicit approval. List commands return at most the first 2,000 results. When a list reaches this limit, the CLI prints a warning.