Deploy with the CLI

Deploying applications on Unkey is in public beta. To try it, select Projects in the dashboard sidebar and create a project. Deployed resources are free until August 1, 2026. We’re eager for feedback, so let us know what you think on Discord, X, or email support@unkey.com.

The unkey deploy command ships a pre-built Docker image to Unkey infrastructure. Unlike the GitHub integration, the CLI does not build your image, you build it yourself (locally or in CI), push it to a registry Unkey can pull from, and unkey deploy creates the deployment and streams status until it is ready. Use the CLI when you want to own the build step: custom CI pipelines, monorepo build systems, pre-release images from a tag, or deploying without connecting a GitHub repository.

Prerequisites

The Unkey CLI installed and authenticated (unkey auth login).
A project created in your workspace.
A Docker image pushed to a registry Unkey can pull from (for example, a public ghcr.io, docker.io, or quay.io image).

We currently don’t support private registries on the platform, this will come in a future release.

Quick start

unkey deploy ghcr.io/your-org/your-app:v1.0.0 --project=my-project

That single command:

Creates a deployment for my-project/default using the image you supplied.
Monitors the deployment status in your terminal with a live spinner.
Prints the deployment ID and assigned domains once the deployment is Ready.

Example output:

Deployment Progress
──────────────────────────────────────────────────
Source Information:
    Branch: main
    Commit: a1b2c3d
    Image: ghcr.io/your-org/your-app:v1.0.0

✓ Deployment created: dep_3f9a2b4c...
✓ Deployment completed successfully

Deployment Complete
  Deployment ID: dep_3f9a2b4c...
  Status: Ready
  Environment: Preview

Domains
  https://my-project-default-git-a1b2c3d-acme.unkey.app

Usage

unkey deploy <docker-image> [flags]

The first positional argument is the fully qualified image reference, registry/repository:tag or registry/repository@sha256:…. The image must already exist in the registry before you run the command.

Flags

Flag	Description	Default
`--project`	Project slug. Required.
`--app`	App slug within the project.	`default`
`--env`	Environment slug to deploy to.	`preview`
`--root-key`	Root key for authentication. Required.
`--api-base-url`	API base URL override (local testing only).

All flags have matching environment variables so the command works cleanly in CI:

export UNKEY_ROOT_KEY=unkey_xxx
export UNKEY_PROJECT=my-project
export UNKEY_APP=api

unkey deploy ghcr.io/your-org/your-app:v1.0.0 --env=production

Git auto-detection

If you run unkey deploy inside a Git working tree, the CLI auto-fills --branch and --commit from the current repository. Set the flags explicitly if you want to override what it detects (for example, when deploying from a CI runner with a detached HEAD). Dirty working trees are recorded with a (dirty) marker in the source info but still deploy.

Deploy from GitHub Actions

A typical CI flow builds the image, pushes it to a registry, then calls unkey deploy:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Install Unkey CLI
        run: npm install -g unkey

      - name: Deploy to Unkey
        env:
          UNKEY_ROOT_KEY: ${{ secrets.UNKEY_ROOT_KEY }}
        run: |
          unkey deploy ghcr.io/${{ github.repository }}:${{ github.sha }} \
            --project=my-project \
            --app=api \
            --env=production \
            --commit=${{ github.sha }} \
            --branch=${{ github.ref_name }}

Store your root key as a repository secret (UNKEY_ROOT_KEY) with permission to deploy to the target project.

What happens after you run the command

The deployment follows the same lifecycle as a GitHub-triggered deployment, with one difference: the Building image step is skipped because Unkey uses the image you supplied as-is.

Deployment record created with status Pending.
Image pulled from the registry.
Containers scheduled across your configured regions.
Health checks run (if configured in app settings).
Domains assigned and routes updated.
Status moves to Ready.

The CLI exits with a non-zero status if the deployment fails, so CI jobs fail loudly when something goes wrong.

Troubleshoot

Symptom	Likely cause
`docker image is required`	You called `unkey deploy` without a positional image argument.
`--project is required`	Pass `--project` or set `UNKEY_PROJECT`.
`--root-key is required`	Pass `--root-key` or set `UNKEY_ROOT_KEY`.
Deployment fails during image pull	The registry is private or the image tag does not exist. Verify the image is pullable publicly.
Deployment reaches Ready but returns 5xx	Check runtime logs in the dashboard, usually a crash on startup or a missing environment variable.

Next steps

CLI vs GitHub integration

When to pick the CLI over the GitHub integration

Deployment lifecycle

How deployments progress from create to serving traffic

App settings

Configure regions, health checks, and variables

CLI overview

Install the CLI and authenticate

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Prerequisites

Quick start

Usage

Flags

Git auto-detection

Deploy from GitHub Actions

What happens after you run the command

Troubleshoot

Next steps

CLI vs GitHub integration

Deployment lifecycle

App settings

CLI overview

​Prerequisites

​Quick start

​Usage

​Flags

​Git auto-detection

​Deploy from GitHub Actions

​What happens after you run the command

​Troubleshoot

​Next steps

CLI vs GitHub integration

Deployment lifecycle

App settings

CLI overview

Prerequisites

Quick start

Usage

Flags

Git auto-detection

Deploy from GitHub Actions

What happens after you run the command

Troubleshoot

Next steps