> ## Documentation Index > Fetch the complete documentation index at: https://cloud.laravel.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Laravel Cloud CLI > Deploy and manage your Laravel Cloud applications from the command line. 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](https://cli.github.com/) (`gh`) or the [GitLab CLI](https://gitlab.com/gitlab-org/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. Repository creation is available only 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: ```bash theme={null} composer global require laravel/cloud-cli ``` *Note:* Make sure your global vendor binaries directory is in your `$PATH` environment variable. You can read more about the global vendor directory in the [Composer documentation](https://getcomposer.org/doc/03-cli.md#global). ### Shell completions The CLI supports tab completions for Bash, Zsh, and Fish. To generate and install completions for your shell, run: ```bash theme={null} cloud completions ``` You can also target a specific shell directly: ```bash theme={null} cloud completions zsh cloud completions bash cloud completions fish ``` ## Authentication Before using the CLI, 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 most direct way to authenticate is through your browser: ```bash theme={null} cloud auth ``` This command opens your default browser, prompts you to authorize the CLI, and stores the resulting API token locally. The CLI saves the token in `~/.config/cloud/config.json`. ### Token authentication In CI/CD pipelines and other environments without a browser, provide an [API token](/docs/api/authentication#create-an-api-token) through the `LARAVEL_CLOUD_TOKEN` environment variable: ```bash theme={null} export LARAVEL_CLOUD_TOKEN=your-api-token cloud application:list ``` 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: ```bash theme={null} LARAVEL_CLOUD_TOKEN= cloud application:list ``` ### 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: ```bash theme={null} cloud auth:token --add --token=your-api-token echo "$API_TOKEN" | cloud auth:token --add ``` 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: ```bash theme={null} cloud auth:token --remove --token=your-api-token ``` To list your tokens, along with the organization each one belongs to and where it was loaded from: ```bash theme={null} cloud auth:token --list ``` 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: ```bash theme={null} cloud ship ``` This guided flow walks you through creating an application, configuring your environment, and deploying, all in a single command. The `ship` command detects your repository and prompts for a region and application name. It can also sync your `.env` variables, create databases or caches, and configure features like the scheduler, Octane, or WebSockets. You may skip some of the prompts by passing options to the `ship` command: ```bash theme={null} cloud ship --name=my-app --region=us-east-2 ``` The following options are available: | Option | Description | | - | - | | `--name` | The application name. Defaults to a name derived from your repository. | | `--region` | The region to create the application in. | | `--database` | The database type: `postgres`, `postgres18`, `postgres17`, `mysql`, or a full type such as `neon_serverless_postgres`. Unversioned aliases use the newest available version. Only applies when running non-interactively. | | `--database-preset` | The database preset: `dev`, `prod`, or `scale`. Only applies when running non-interactively. | | `--source-provider` | The source provider: `github`, `gitlab`, `gitlab_self_hosted`, or `bitbucket`. Defaults to the provider detected from your `origin` remote. | | `--root-directory` | The repository subdirectory that contains your application, for monorepos. | 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: ```bash theme={null} cloud deploy ``` 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: ```bash theme={null} cloud deploy --open ``` 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: ```bash theme={null} cloud deploy --no-wait ``` You can also monitor an active deployment separately: ```bash theme={null} cloud deploy:monitor ``` 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: ```bash theme={null} cloud deployment:list cloud deployment:get cloud deployment: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: ```bash theme={null} cloud repo:config ``` The command creates a `.cloud/config.json` file in your project root that stores the `application_id` and `organization_id`. Subsequent commands use these defaults automatically. ## Managing resources The CLI provides full CRUD operations for Laravel Cloud resources. The following examples show the most common operations. ### Applications ```bash theme={null} cloud application:list cloud application:get cloud application:create cloud application:update cloud application:delete ``` ### Environments ```bash theme={null} cloud environment:list cloud environment:get cloud environment:create cloud environment:update cloud environment:delete ``` To update environment variables interactively or by using command options: ```bash theme={null} cloud environment:variables ``` To view environment logs: ```bash theme={null} cloud 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 takes effect only on the next deployment. 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: ```bash theme={null} cloud environment:vanity-domain --name=my-app --deploy ``` To purge the environment's edge cache, run `environment:purge-edge-cache`. By default, the command purges everything cached at the edge. 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: ```bash theme={null} cloud environment:purge-edge-cache cloud environment:purge-edge-cache --path=/blog/hello-world cloud environment:purge-edge-cache --prefix=/blog/ ``` To list the [secrets](/docs/secrets) attached to an environment, or attach secrets to it: ```bash theme={null} cloud environment-secret:list cloud environment-secret:attach ``` ### Instances ```bash theme={null} cloud instance:list cloud instance:get cloud instance:create cloud instance:update cloud instance:delete cloud instance:sizes ``` ### Databases ```bash theme={null} cloud database-cluster:list cloud database-cluster:get cloud database-cluster:create cloud database-cluster:update cloud database-cluster:delete ``` To manage individual databases within a cluster: ```bash theme={null} cloud database:list cloud database:get cloud database:create cloud database:delete ``` To open a database in your local database client: ```bash theme={null} cloud database:open ``` To manage database snapshots and restores: ```bash theme={null} cloud database-snapshot:list cloud database-snapshot:get cloud database-snapshot:create cloud database-snapshot:delete cloud database-restore:create ``` ### Caches ```bash theme={null} cloud cache:list cloud cache:get cloud cache:create cloud cache:update cloud cache:delete cloud cache:types ``` ### Object storage ```bash theme={null} cloud bucket:list cloud bucket:get cloud bucket:create cloud bucket:update cloud bucket:delete ``` To manage bucket keys separately: ```bash theme={null} cloud bucket-key:list cloud bucket-key:get cloud bucket-key:create cloud bucket-key:update cloud bucket-key:delete ``` ### Domains ```bash theme={null} cloud domain:list cloud domain:get cloud domain:create cloud domain:update cloud domain:delete cloud domain:verify ``` ### WebSockets ```bash theme={null} cloud websocket-cluster:list cloud websocket-cluster:get cloud websocket-cluster:create cloud websocket-cluster:update cloud websocket-cluster:delete ``` To manage WebSocket applications within a cluster: ```bash theme={null} cloud websocket-application:list cloud websocket-application:get cloud websocket-application:create cloud websocket-application:update cloud websocket-application:delete ``` ### Background processes ```bash theme={null} cloud background-process:list cloud background-process:get cloud background-process:create cloud background-process:update cloud background-process:delete ``` ### Managed queues [Managed queues](/docs/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: ```bash theme={null} cloud managed-queue:create cloud managed-queue:pause cloud managed-queue:resume cloud managed-queue:purge cloud managed-queue:set-default ``` 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: ```bash theme={null} cloud managed-queue:failed-jobs cloud managed-queue:retry-failed-job cloud managed-queue:delete-failed-job ``` The `pause`, `purge`, and `delete-failed-job` commands accept the `--force` option to skip the confirmation prompt. ### Secrets [Secrets](/docs/secrets) are encrypted values shared across your organization. You can attach them to environments: ```bash theme={null} cloud secret:list cloud secret:create cloud secret:update cloud secret:delete ``` The `secret:create` and `secret:update` commands read the secret's value from `STDIN` when you don't pass the `--value` option. Reading from `STDIN` keeps the value out of your shell history: ```bash theme={null} op read "op://vault/stripe/api-key" | cloud secret:create --name=STRIPE_KEY ``` The CLI encrypts values on your machine with PHP's `sodium` extension before sending them to Laravel Cloud. Some Linux distributions ship this extension as a separate package. ### Commands To run a one-off command on an environment: ```bash theme={null} cloud command:run ``` To list previously executed commands: ```bash theme={null} cloud command:list cloud command:get ``` ### Tinker The `tinker` command opens an interactive PHP REPL connected to your Laravel Cloud environment. You can execute PHP code directly against your running application: ```bash theme={null} cloud tinker ``` By default, the CLI presents a multi-line text input in your terminal where you can type and submit PHP code. The CLI sends each submission to your Cloud environment for execution and displays the result 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: ```bash theme={null} cloud tinker --editor=code ``` The CLI opens a temporary file in your editor. Every time you save the file, the CLI sends the code to your Cloud environment for execution and displays the result in your terminal. The session ends when you close the file. Common editor values include `code`, `subl`, `vim`, and `phpstorm`. If you don't give a value, the CLI uses the `VISUAL` or `EDITOR` environment variable. #### Non-interactive mode To execute a single snippet of PHP code without entering the interactive session, use the `--code` option: ```bash theme={null} cloud tinker --code="echo App\Models\User::count();" ``` Non-interactive mode is useful for scripting and CI/CD pipelines. #### Timeout By default, code execution times out after 60 seconds. You can adjust this with the `--timeout` option: ```bash theme={null} cloud tinker --timeout=120 ``` ## Metrics and usage To view metrics for an environment, database cluster, cache, WebSocket cluster, or WebSocket application: ```bash theme={null} cloud environment:metrics cloud database-cluster:metrics cloud cache:metrics cloud websocket-cluster:metrics cloud websocket-application:metrics ``` Metrics cover the past 24 hours by default. Use the `--period` option to choose `6h`, `24h`, `3d`, `7d`, or `30d`: ```bash theme={null} cloud environment:metrics --period=7d ``` To view your organization's [usage](/docs/usage) and billing summary for the current billing period: ```bash theme={null} cloud usage ``` Pass `--detailed` for a full breakdown by application, resource, and add-on. Pass `--environment` to filter usage by environment, or `--period` to view a different billing period. The `--period` option accepts `current`, `previous`, `1`, `2`, or `3`: ```bash theme={null} cloud usage --detailed --period=previous ``` ## Utility commands Open your application in the Laravel Cloud dashboard: ```bash theme={null} cloud dashboard ``` Open your application in the browser: ```bash theme={null} cloud browser ``` Retrieve Laravel Cloud IP addresses by region: ```bash theme={null} cloud ip:addresses ``` List your organization's dedicated clusters: ```bash theme={null} cloud dedicated-cluster:list ``` ## Agent skills The CLI can install Laravel Cloud skills for your AI coding agents. The CLI fetches skills from the `laravel/agent-skills` repository and installs them into the appropriate directory for each agent. ```bash theme={null} cloud skills:install ``` The command detects which agents you have configured and prompts you to select the ones to install skills for. Supported agents include Claude, Cursor, Junie, GitHub Copilot, and a generic agent format. ### Global vs. project installation By default, the CLI installs skills to the current project if the project lists the Cloud CLI as a Composer dependency. Otherwise, it installs them globally. You can override this behavior: ```bash theme={null} # Install globally (e.g. ~/.claude/skills) cloud skills:install --global # Install to the current project (e.g. .claude/skills) cloud skills:install --project ``` ### Specifying agents To install skills for specific agents without being prompted: ```bash theme={null} cloud skills:install --agent=claude --agent=cursor ``` ### Overwriting existing skills If you have already installed skills, use the `--force` flag to overwrite them: ```bash theme={null} cloud skills:install --force ``` ## JSON output Many commands support a `--json` flag for machine-readable output, which is useful for automation and CI/CD pipelines: ```bash theme={null} cloud instance:list --json cloud environment:variables --json --action=set --key=APP_ENV --value=production ``` The CLI writes JSON output to `STDOUT` and errors 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. To reveal them, pass `--show-sensitive`: ```bash theme={null} cloud environment:get --json --show-sensitive ``` 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.