Skip to main content
Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. 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 deployments create followed by polling deployments get.
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 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
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
Accepted, but not sent in the deployment request. The command reads commit metadata from the checkout’s HEAD regardless of this flag. Outside a Git repository, it sends no commit metadata.
string
Root key. Falls back to UNKEY_ROOT_KEY, then the CLI session from unkey login when that session belongs to this API, then a root key saved with unkey login --root-key.
string
API base URL. Falls back to UNKEY_API_BASE_URL. When empty, a CLI session is sent to the API URL stored at login, and a root key uses https://api.unkey.com. A different host skips the stored session.
The command doesn’t accept --output, --config, or --body.

Required permissions

The root key needs #write permission on unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/* to create the deployment. It also needs #read permission on the created deployment to follow it. You can use the same resource wildcard with both actions. The workspace must match the root key’s authorized workspace. Use the project, app, and environment IDs that match the request’s slugs. See Root key permissions.

What you’ll see

The command writes the project, app, environment, image, and progress messages to stderr. Final deployment details and domains go to stdout. Inside a Git repository, it sends the branch and available HEAD metadata, including the commit SHA, message, author, and commit time. It doesn’t send a dirty-checkout marker. Spinners and colors appear only when stderr is a terminal. With redirected stderr or TERM=dumb, progress is plain text without spinners or color codes. Set NO_COLOR to any nonempty value to disable color in a terminal; the spinner can still run. If the deployment can’t be created, the command writes the error to stderr 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 deployment #write permission, 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 the final deployment details and domains to stdout and exits 0. Progress completion stays on stderr.
  • Failed: writes the error message (or Unknown deployment error) to stderr 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 deployments get.

Examples

Deploy to the preview environment of the default app:
Deploy to production with the key from the environment, as in CI:
Save the final result separately from plain progress output:
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 November 11, 2026