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.
Create a deployment for an in one of its . With no source flag, the app deploys its usual source: a Git app builds its default branch, and an image app deploys its default image. That’s what you want in CI for a routine redeploy. To deploy something else, pass one source flag:
  • --oci deploys a prebuilt image, with no build. A tag like latest is pinned to the exact image it points to when you deploy.
  • --git builds a branch, commit, or fork commit from the app’s connected repository.
  • --deployment redeploys an existing deployment. A Git deployment rebuilds from its commit, and an image deployment reuses its image.
You can pass only one of them. The command returns a deploymentId right away, while the build and rollout keep running. Poll get-deployment to follow the status. Deploying needs an active Compute plan. Without one the API answers 412 with The workspace has no active Compute plan. A workspace over its Compute spend cap gets The workspace is suspended by its Compute spend cap. Raise the spend limit to resume. See Compute plans.

​
Usage

​
Flags

​
string
required
App ID or slug.
​
string
Existing deployment to re-run, as a JSON object with a deploymentId field. It must be in the same app and environment. Any other ID returns The specified deployment does not exist.
​
string
required
Environment ID or slug the deployment lands in.
​
string
Git source as a JSON object with branch, commitSha, or a fork’s repository plus commitSha, for example {"branch":"main"}. Requires the app to have a repository connected.
​
string
OCI image source as a JSON object with a required image field. A tag is pinned to the exact image it points to when you deploy.
​
string
required
Project ID or slug. Both forms resolve to the same project.

​
Shared flags

Every unkey api command accepts these; CLI output and shared flags describes them in full.
​
string
A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See Send a raw body.
​
string
Root key for the request. Falls back to UNKEY_ROOT_KEY, then to the config file written by unkey auth login. See CLI authentication.
​
string
default:"https://api.unkey.com"
Base URL of the API. Falls back to UNKEY_API_BASE_URL. You don’t normally need to set it.
​
string
default:"~/.unkey/config.toml"
Path of the TOML file that unkey auth login writes. Falls back to UNKEY_CONFIG.
​
string
Output format. Falls back to UNKEY_OUTPUT. Set json to print the full response envelope (meta and data) for piping; any other value prints the request ID followed by data.

​
Required permissions

Your root key needs one of:
  • environment.*.create_deployment (any environment)
  • environment.<environment_id>.create_deployment (a specific environment)
Without a matching permission the API answers 403 and the CLI prints Permission denied: followed by the detail. See Root key permissions for the full catalog.

​
Examples

Deploy the app’s configured source:
Build and deploy a specific branch:
Deploy a prebuilt image:
Send the request body as JSON and capture the ID:

​
API endpoint

The command calls POST /v3/deployments.createDeployment and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.

Deployments

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

unkey deploy

The one-shot command that deploys an image and waits for it.
Last modified on September 29, 2026