cli

Unikraft CLI

[!NOTE]

This is the new Unikraft CLI which will eventually supersede kraft cloud. It is still in early development and subject to change before the v1.0.0 release. Feedback appreciated!

The official command-line interface for Unikraft Cloud — deploy and manage unikernels globally in milliseconds.

Features

• Deploy Instantly — Run unikernel images as serverless instances with unikraft run
• Global Infrastructure — Deploy across multiple metros with automatic multi-region support
• Resource Management — Full CRUD operations for instances, volumes, services, certificates, and images
• Scale-to-Zero — Built-in support for scale-to-zero policies to optimize costs
• Multiple Output Formats — Machine-readable JSON or human-friendly text output
• Profile Management — Switch between multiple accounts and configurations
• Shell Completions — Tab completion for Bash, Zsh, Fish, and PowerShell

Installation

curl --proto '=https' --tlsv1.2 -fsSL https://unikraft.com/cli/install.sh | sh

brew install unikraft/tap/unikraft

# Update and install dependencies
sudo apt update
sudo apt install ca-certificates curl

# Download and add the GPG key
sudo install -d -m 0755 /etc/apt/keyrings

sudo curl -fsSL \
  -o /etc/apt/keyrings/unikraft-cli.gpg \
  https://pkg.unikraft.com/debian/cli-apt/keys/cli-apt.gpg

sudo tee /etc/apt/sources.list.d/unikraft-cli.sources <<EOF
Types: deb
URIs: https://pkg.unikraft.com/debian/cli-apt/
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Signed-By: /etc/apt/keyrings/unikraft-cli.gpg
EOF

# Update and install the CLI
sudo apt update
sudo apt install unikraft-cli

# Add the Unikraft CLI repository
sudo tee /etc/yum.repos.d/unikraft-cli-rpm.repo <<EOF
[unikraft]
name=unikraft
baseurl=https://pkg.unikraft.com/rpm/cli-rpm/
gpgcheck=0
enabled=1
EOF

# Install the CLI at the specific pre-release version
yum install unikraft-cli

- name: Install Unikraft CLI
  uses: unikraft/setup-action@v1

# Clone the repository
git clone https://github.com/unikraft/cli.git
cd cli

# Build the CLI
make cli

# The binary is available at dist/unikraft
./dist/unikraft --version

Quick Start

1. Login to Unikraft Cloud

unikraft login

This opens your browser for authentication. Alternatively, provide a token file:

unikraft login --token /path/to/token

Or, if you need to directly specify a metro endpoint, you can manually create a profile:

# Linux: ~/.config/unikraft/config.yaml
# MacOS: ~/Library/Application\ Support/unikraft/config.yaml
profile: default
profiles:
  default:
    type: cloud
    organization: <org-name>
    token: <api-token>
    metros:
      - name: <metro-name> # e.g. fra
        endpoint: <metro-endpoint> # e.g. https://api.fra.unikraft.cloud
        country: <metro-country> # e.g. de
        insecure: false # skip tls verification (avoid for production use)

You can also easily migrate your old UKC_METRO/UKC_TOKEN environment variable setup to a profile:

# Linux: ~/.config/unikraft/config.yaml
# MacOS: ~/Library/Application\ Support/unikraft/config.yaml
profile: default
profiles:
  default:
    type: legacy

2. Deploy Your First Instance

unikraft run --metro=fra -p 443:8080/http+tls --image=nginx:latest

This deploys an NGINX instance in Frankfurt with HTTPS enabled.

3. List Your Instances

unikraft instances list

4. View Instance Logs

unikraft instances logs my-instance

Commands

Examples

Deploy with environment variables:

unikraft run --metro=sfo -e KEY=VALUE -e DEBUG=true --image=my-app:latest

Deploy with an attached volume:

unikraft run --metro=was -v my-volume:/data --image=my-app:latest

Deploy with custom resources:

unikraft run --metro=dal -m 512MiB --vcpus 2 --image=my-app:latest

Deploy with scale-to-zero:

unikraft run --metro=sin --scale-to-zero policy=on,cooldown-time=300 --image=my-app:latest

Create an instance with multiple service ports:

unikraft run --metro=fra -p 443:8080/http+tls -p 80:443/http+redirect --image=nginx:latest

Edit an existing instance:

unikraft instances edit my-instance --set image=nginx:1.27

Clone a volume:

unikraft volumes clone my-volume --set name=my-volume-backup

Build and publish an image from a Kraftfile:

unikraft build . --output my-org/my-app:latest

Configuration

The CLI stores configuration in ~/.config/unikraft/config.yaml (or the path specified by UNIKRAFT_CONFIG).

Environment Variables

Profiles

Manage multiple accounts or configurations with profiles:

# List profiles
unikraft profile list

# Switch profile
unikraft profile use staging

# Use a profile for a single command
unikraft --profile=staging instances list

Output Formats

The CLI supports multiple output formats via the -o flag:

# Default table output
unikraft instances list

# JSON output
unikraft instances list -o json

# Show specific fields
unikraft instances get my-instance --fields name,state,image

# Include verbose/detailed fields
unikraft instances get my-instance -v

Development

Prerequisites

• Go 1.25+
• Git
• GNU Make which transparently wraps Task

Build

make cli

The binary is placed in dist/unikraft.

Test

# Run unit tests
make test

# Run linter
make lint

# Run integration tests (requires setup)
make integration

# Update integration test golden files
make integration-update

Documentation

# Generate all docs
make docs

# Generate man pages only
make docs:man

# Generate markdown docs only
make docs:mdx

Output is placed in dist/docs/.

Architecture

The CLI follows a resource-oriented architecture:

• Commands (internal/cmd/) — Kong-based command definitions with subcommand routing
• Resources (internal/resource/) — Unified interface for API objects with field introspection
• Multi-Metro (internal/multimetro/) — Client abstraction for global infrastructure operations
• Configuration (internal/config/) — Profile and credential management
• Telemetry (internal/telemetry/) — Anonymous usage analytics (opt-out via --no-telemetry)

Key Dependencies

• Kong — CLI parsing and command wiring
• Bubble Tea — Terminal UI components
• Unikraft Cloud SDK — API client library

Shell Completion

Generate completion scripts for your shell:

# Bash
unikraft completion bash > /etc/bash_completion.d/unikraft

# Zsh
unikraft completion zsh > "${fpath[1]}/_unikraft"

# Fish
unikraft completion fish > ~/.config/fish/completions/unikraft.fish

# PowerShell
unikraft completion powershell > unikraft.ps1

Telemetry

The CLI collects anonymous usage analytics to improve the product. No personally identifiable information is collected. To opt out:

# Disable for a single command
unikraft --no-telemetry instances list

# Disable permanently
export UNIKRAFT_TELEMETRY=false

# Or
export DO_NOT_TRACK=1

License

BSD-3-Clause. See LICENSE.md for details. Copyright (c) 2026, Unikraft GmbH and The Unikraft CLI Authors.

Links

• Unikraft Cloud Documentation
• Report Issues
• Unikraft Website