Skip to main content
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
Deploy a prebuilt container image to an and wait until it’s live or has failed. It’s a shortcut for create-deployment followed by polling get-deployment.
unkey deploy relies on endpoints that aren’t part of the public API reference and can change without notice. For scripts that must not break, use the unkey api deployments commands, which call the stable deployments.* endpoints.

​
Usage

The image is required. Without it, the command exits with docker image is required. The image must already be in a registry we can pull from. Nothing is built.

​
Flags

​
string
required
Project slug the app belongs to. Falls back to UNKEY_PROJECT.
​
string
default:"default"
App slug within the project. Falls back to UNKEY_APP.
​
string
default:"preview"
Slug of the to deploy to. Pass production to deploy to production.
​
string
Keyspace whose keys the gateway accepts for this deployment. Falls back to UNKEY_KEYSPACE_ID. See API key authentication.
​
string
default:"main"
Git branch recorded on the deployment. If you leave the default and you’re in a Git checkout on another branch, the CLI uses that branch.
​
string
Commit SHA recorded on the deployment. Defaults to the HEAD of your Git checkout. Outside a Git repository, no commit is recorded unless you pass this. If you pass a SHA other than HEAD, only the SHA is recorded, without the commit message or author.
​
string
required
Root key. Falls back to UNKEY_ROOT_KEY. Unlike the unkey api commands, unkey deploy doesn’t read ~/.unkey/config.toml, so a key saved with unkey auth login doesn’t work here.
​
string
API base URL. Falls back to UNKEY_API_BASE_URL. When empty, https://api.unkey.com is used. You don’t normally need to set it.
The command doesn’t accept --output, --config, or --body.

​
Required permissions

project.*.create_deployment or project.<project_id>.create_deployment to create the deployment, and project.*.read_deployment or project.<project_id>.read_deployment to follow it. These are project permissions. The unkey api deployments commands use environment permissions instead. See Root key permissions.

​
What you’ll see

The command prints a Deployment Progress header with the branch, commit, and image. Inside a Git repository, it records the branch, commit, message, author, and commit time on the deployment so the dashboard can show them, and marks the commit as dirty if you have uncommitted changes. If the deployment can’t be created, the command prints the error and exits 1. Common causes are a --project or --app that doesn’t exist, an --env that isn’t an environment of that app, a root key without create_deployment, an image reference we can’t parse, or a --keyspace-id that isn’t in your workspace. Otherwise it follows the deployment until it finishes:
  • Ready: prints Deployment completed successfully, the deployment ID, the environment, and its hostnames, and exits 0.
  • Failed: prints the error message (or Unknown deployment error) and exits 1, so a CI job fails.
  • Still going after 5 minutes: exits with deployment timeout after 5 minutes. The deployment keeps going. Follow it with unkey api deployments get-deployment.

​
Examples

Deploy to the preview environment of the default app:
Deploy to production with the key from the environment, as in CI:
Deploy behind API key authentication:

Deploy an image

The guided walkthrough from first image to first request.

Deployments

Statuses, the build queue, and why a deployment fails.

CLI authentication

Where the root key comes from and why unkey deploy differs.
Last modified on September 29, 2026