> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey deploy

> Deploy a prebuilt container image to a project with one command.

<Note>
  You need a root key with the permissions listed on this page. Create one in the dashboard under **Settings > Root Keys**. See [Permission reference](/docs/platform/root-keys/permissions-legacy) for every permission.
</Note>

Deploy a prebuilt container image to an <Tooltip tip="A Compute app: a deployable service inside a project. Not your application in general.">app</Tooltip> and wait until it's live or has failed. It's a shortcut for [create-deployment](/docs/compute/cli/deployments/create-deployment) followed by polling [get-deployment](/docs/compute/cli/deployments/get-deployment).

<Warning>
  `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.
</Warning>

## Usage

```bash theme={"system"}
unkey deploy <docker-image> --project=<project> --root-key=<root key> [flags]
```

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

<ParamField body="--project" type="string" required>
  Project slug the app belongs to. Falls back to `UNKEY_PROJECT`.
</ParamField>

<ParamField body="--app" type="string" default="default">
  App slug within the project. Falls back to `UNKEY_APP`.
</ParamField>

<ParamField body="--env" type="string" default="preview">
  Slug of the <Tooltip tip="A production or preview environment of a Compute app, not the dashboard label on a key.">environment</Tooltip> to deploy to. Pass `production` to deploy to production.
</ParamField>

<ParamField body="--keyspace-id" type="string">
  Keyspace whose keys the gateway accepts for this deployment. Falls back to `UNKEY_KEYSPACE_ID`. See [API key authentication](/docs/compute/gateway/api-key-auth).
</ParamField>

<ParamField body="--branch" type="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.
</ParamField>

<ParamField body="--commit" type="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.
</ParamField>

<ParamField body="--root-key" type="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.
</ParamField>

<ParamField body="--api-base-url" type="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.
</ParamField>

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](/docs/platform/root-keys/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:

```bash theme={"system"}
unkey deploy ghcr.io/acme/payments:1.4.2 --project=payments --root-key=unkey_xxx
```

Deploy to production with the key from the environment, as in CI:

```bash theme={"system"}
export UNKEY_ROOT_KEY=unkey_xxx
unkey deploy myregistry.io/payments-api:latest --project=payments --app=payments-api --env=production
```

Deploy behind API key authentication:

```bash theme={"system"}
unkey deploy ghcr.io/acme/payments:1.4.2 --project=payments --app=payments-api --env=production --keyspace-id=ks_1234abcd
```

## Related

<Columns cols={2}>
  <Card title="Deploy an image" href="/docs/compute/get-started/deploy-an-image">
    The guided walkthrough from first image to first request.
  </Card>

  <Card title="Deployments" href="/docs/compute/concepts/deployments">
    Statuses, the build queue, and why a deployment fails.
  </Card>

  <Card title="CLI authentication" href="/docs/platform/cli/authentication">
    Where the root key comes from and why `unkey deploy` differs.
  </Card>
</Columns>