CLI Reference

Global Flags
VM Commands
1. uni run
2. uni ps
3. uni logs
4. uni inspect
5. uni stop
6. uni rm
7. uni cp
8. uni exec
Image Commands
Package Commands
Volume Commands
Kernel Commands
Upgrade Commands
Compose Commands
VM States

Global Flags

Every uni command accepts these flags:

Flag	Default	Description
`--socket`	`/var/run/unid.sock` (Linux) / `%TEMP%\unid.sock` (Windows)	Path to the `unid` Unix socket
`--store`	`~/.uni/images`	Local image store directory
`--output`	`table`	Output format: `table` or `json`

VM Commands

`uni run`

Create and immediately start a unikernel VM.

uni run <image> [flags]

<image> can be:

A file path: ./myapp.img — path to a pre-built bootable disk image
A name:tag reference: hello:latest — looked up in the local image store

Note: uni run requires a bootable disk image, not a raw ELF binary. To package a binary into an image first run uni build --name <name> <binary>, then uni run <name>:latest.

Flags:

Flag	Default	Description
`--memory`	`256M`	VM memory (e.g. `256M`, `1G`, `4G`)
`--cpus`	`1`	Number of virtual CPUs
`-p`, `--port`	—	Publish port(s): `host:guest[/tcp\\|udp]` (repeatable)
`-e`, `--env`	—	Set environment variable `KEY=VALUE` (repeatable)
`--env-file`	—	Read environment variables from file (one `KEY=VALUE` per line)
`--name`	—	Assign a human-readable name to the VM instance
`--rm`	`false`	Automatically remove the VM when it stops
`-v`, `--volume`	—	Mount a named volume: `name:guestpath[:ro]` (repeatable)
`--attach`	`false`	Attach to VM serial console (blocks until VM stops)
`-d`, `--detach`	`true`	Run VM in the background (overridden by `--attach`)
`--ip`	—	Static IP address, configured in the guest via fw_cfg (requires `--network`)
`--network`	—	TAP interface name to attach (Linux only)

Examples:

# Run from a pre-built disk image file
uni run ./myapp.img --memory 512M --cpus 2

# Run a built image by name
uni run myapp:latest

# Expose port 8080 on the host → port 80 inside the VM
uni run nginx:latest -p 8080:80

# Multiple ports and UDP
uni run myapp:latest -p 8080:80 -p 5353:53/udp

# Pass environment variables
uni run myapp:latest -e NODE_ENV=production -e PORT=3000

# Load env vars from a file
uni run myapp:latest --env-file .env

# Mount a named volume (create first with 'uni volume create')
uni run myapp:latest -v data:/var/data

# Read-only volume mount
uni run myapp:latest -v config:/etc/app:ro

# Named instance, auto-remove on exit
uni run hello:latest --name web --rm

# Attach to serial console (blocks until VM exits)
uni run hello:latest --attach

# Attach with a named instance and port
uni run myapp:latest --name api --attach -p 8080:8080

# Run with TAP networking and static IP (Linux only)
uni run myapp:latest --network tap0 --ip 192.168.100.10 -p 8080:80

# Output the VM ID for scripting
ID=$(uni run hello:latest --name api)
echo "Started VM: $ID"

Output:

a3f8c2d1-7b4e-4a1f-8c2d-1a2b3c4d5e6f

With --attach, the command blocks and streams the VM’s serial console output to stdout until the VM stops. No VM ID is printed in attach mode.

`uni ps`

List all registered VMs.

uni ps

Examples:

uni ps
# ID                                    STATE    IMAGE
# a3f8c2d1-7b4e-4a1f-8c2d-1a2b3c4d5e6f  running  hello:latest
# b4e9d3e2-8c5f-5b2g-9d3e-2b3c4d5e6f7a  stopped  api:v2

# JSON output
uni --output json ps

JSON output:

[
  {
    "id": "a3f8c2d1-7b4e-4a1f-8c2d-1a2b3c4d5e6f",
    "state": "running",
    "image": "hello:latest"
  }
]

`uni logs`

Print captured serial console output (stdout + stderr) for a VM.

uni logs <id>

Example:

uni logs a3f8c2d1
# Hello from unikernel!
# tick 1
# tick 2

Logs are buffered in memory by unid. They are lost when the daemon restarts. For real-time streaming, use uni run --attach instead, which blocks and streams the serial console output directly to your terminal as the VM runs.

`uni inspect`

Display full details for a VM as JSON.

uni inspect <id>

Example:

uni inspect a3f8c2d1

{
  "id": "a3f8c2d1-7b4e-4a1f-8c2d-1a2b3c4d5e6f",
  "state": "running",
  "image": "hello:latest",
  "name": "web",
  "memory": "256M",
  "cpus": 1,
  "ports": [
    {"host_port": 8080, "guest_port": 80, "protocol": "tcp"}
  ],
  "env": ["NODE_ENV=production", "PORT=3000"],
  "volumes": [
    {"disk_path": "/home/user/.uni/volumes/data/disk.img", "guest_path": "/var/data", "read_only": false}
  ],
  "created_at": "2026-04-19T10:00:00Z",
  "started_at": "2026-04-19T10:00:01Z"
}

`uni stop`

Gracefully stop a running VM.

uni stop <id> [--force]

Shutdown sequence (without --force):

Send SIGTERM to the QEMU process
Wait up to 30 seconds for the VM to exit cleanly
Send SIGKILL if still running after the grace period

Flag	Default	Description
`--force`	`false`	Skip grace period, send `SIGKILL` immediately

Examples:

# Graceful shutdown
uni stop a3f8c2d1

# Immediate kill
uni stop --force a3f8c2d1

`uni rm`

Remove a stopped VM from the registry.

uni rm <id>

The VM must be in stopped state. Run uni stop <id> first.

Example:

uni stop a3f8c2d1
uni rm a3f8c2d1

`uni cp`

Copy files to or from a stopped VM disk image. The dump and mkfs tools are downloaded automatically on first use from the kernel release.

uni cp <src> <dst>

One operand must be a VM reference in the form id:path, the other a local file path. Copying to a VM rebuilds the disk image with the new file included.

Examples:

# Copy a file from a stopped VM to the host
uni cp myvm:/etc/config.json ./config.json
# copied myvm:/etc/config.json → ./config.json

# Copy a file from the host into a stopped VM
uni cp ./local.conf myvm:/etc/config.json
# copied ./local.conf → myvm:/etc/config.json

# Copy from a VM identified by prefix
uni cp a3f8:/var/log/app.log ./app.log

`uni exec`

Send a signal to a running VM process.

uni exec <id> --signal <SIG>

Flag	Default	Description
`--signal`	`SIGTERM`	Signal name (e.g. `SIGTERM`, `SIGHUP`) or number (e.g. `15`)

Examples:

# Reload configuration (if the app handles SIGHUP)
uni exec a3f8c2d1 --signal SIGHUP

# Send signal by number
uni exec a3f8c2d1 --signal 1

Supported signal names: SIGTERM, SIGINT, SIGKILL, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2

Image Commands

`uni build`

Build a unikernel image from a static ELF binary.

uni build <binary> [flags]

The binary must be a static Linux ELF (GOOS=linux, no dynamic library dependencies). Go binaries built with CGO_ENABLED=0 GOOS=linux are ideal.

Flag	Default	Description
`--name`	Binary filename	Image name
`--tag`	`latest`	Image tag
`--memory`	`256M`	Default VM memory baked into the image
`--cpus`	`1`	Default CPU count baked into the image
`--mkfs`	(auto-downloaded to `~/.uni/tools/mkfs`)	Path to Nanos mkfs binary — overrides auto-download (env: `UNI_MKFS`)
`-U`, `--update-kernel`	`false`	Auto-approve kernel update if one is available (skips the `[y/N]` prompt)
`--pkg`	—	Include package in the image (repeatable). Downloads, extracts, and includes the package files

If the kernel tools are already cached and a newer kernel version is available, uni build will prompt before proceeding:

⚠  New kernel version available: v0.1.1 (installed: v0.1.0)
Update kernel before building? [y/N]

Examples:

# Basic build
uni build ./hello

# Custom name and tag
uni build ./myapi --name api --tag v1.2.0

# With resource defaults
uni build ./api --name api --tag latest --memory 512M --cpus 2

# Include a runtime package
uni build ./myapp --name myapp --pkg node:20

# Include multiple packages
uni build ./myapp --name myapp --pkg node:20 --pkg redis:7

Output:

sha256:abc123def456...  api:latest

`uni images`

List all images in the local store.

uni images

Example:

uni images
# DIGEST              NAME   TAG     CREATED               SIZE
# sha256:abc123def4   hello  latest  2026-04-19T10:00:00Z  12.0MB
# sha256:def456ghi7   api    v1.2.0  2026-04-19T11:00:00Z  24.3MB

`uni rmi`

Remove an image from the local store.

uni rmi <ref>

<ref> can be name:tag or sha256:<hex>.

Example:

uni rmi hello:latest
# hello:latest

`uni push`

Push a local image to a registry.

uni push <ref> <registry-url>

Example:

uni push hello:latest http://registry.example.com:5000
# pushed hello:latest to http://registry.example.com:5000

`uni pull`

Pull an image from a registry into the local store.

uni pull <ref> <registry-url>

Example:

uni pull hello:latest http://registry.example.com:5000
# sha256:abc123...  hello:latest

Package Commands

Manage pre-packaged files that can be included in images at build time. Packages are cached locally in ~/.uni/packages/.

`uni pkg list`

List locally cached packages.

uni pkg list

uni pkg list
# NAME       VERSION   SIZE
# redis      7.2       12.5MB
# nginx      1.25      8.3MB

`uni pkg search`

Search the remote package index.

uni pkg search <query>

uni pkg search redis
# NAME       VERSION   SIZE      DESCRIPTION
# redis      7.2       12.5MB    In-memory data store
# redis-cli  7.2       3.1MB     Redis command-line client

`uni pkg get`

Download and install a package from the remote index.

uni pkg get <name>[:version]

# Install the latest version
uni pkg get redis

# Install a specific version
uni pkg get redis:7.2

`uni pkg remove`

Remove locally cached package(s). Without a version suffix, all versions of the package are removed.

uni pkg remove <name>[:version]

# Remove a specific version
uni pkg remove redis:7.2

# Remove all locally cached versions
uni pkg remove redis
# Removed all versions of package redis.

Volume Commands

Volumes are named persistent disk images that survive VM restarts. Create a volume once, then mount it into any VM with -v.

`uni volume create`

Create a new named volume.

uni volume create <name> [--size <size>]

Flag	Default	Description
`--size`	`1G`	Volume size: `512M`, `1G`, `2G`, etc.

Example:

uni volume create mydata --size 2G
# mydata

uni volume create config --size 512M
# config

`uni volume ls`

List all volumes.

uni volume ls [--output json]

uni volume ls
# NAME     SIZE   CREATED
# mydata   2.0G   2026-04-25 18:00:00
# config   512.0M 2026-04-25 18:01:00

`uni volume inspect`

Show full details for a volume as JSON.

uni volume inspect <name>

uni volume inspect mydata

{
  "id": "mydata",
  "disk_path": "/home/user/.uni/volumes/mydata/disk.img",
  "size_bytes": 2147483648,
  "created_at": "2026-04-25T18:00:00Z"
}

`uni volume rm`

Remove a volume and its disk image permanently.

uni volume rm <name>

This is irreversible. All data stored in the volume will be lost.

uni volume rm mydata
# mydata

Kernel Commands

Manage the kernel tools (kernel.img, boot.img, mkfs) cached in ~/.uni/tools/. The kernel is versioned independently from the CLI.

`uni kernel check`

Show the installed kernel version and whether a newer one is available.

uni kernel check

uni kernel check
# Installed kernel: v0.1.0
# Latest kernel:    v0.1.1
# Update available. Run `uni kernel update` to install v0.1.1.

`uni kernel update`

Download and install the latest kernel tools.

uni kernel update [--yes]

Flag	Default	Description
`-y`, `--yes`	`false`	Skip confirmation prompt

uni kernel update
# New kernel version available: v0.1.1 (installed: v0.1.0)
# Update? [y/N] y
# Downloading kernel.img...
# Kernel updated to v0.1.1.

`uni kernel list`

List all available kernel versions, newest first. The currently installed version is marked with *.

uni kernel list

uni kernel list
# * v0.1.1
#   v0.1.0

`uni kernel use`

Switch to a specific kernel version.

uni kernel use <version> [--yes]

Flag	Default	Description
`-y`, `--yes`	`false`	Skip confirmation prompt

uni kernel use v0.1.0
# Switching kernel: v0.1.1 → v0.1.0
# Proceed? [y/N] y
# Kernel switched to v0.1.0.

Upgrade Commands

Manage the uni and unid binaries themselves. The CLI is versioned independently from the kernel.

`uni upgrade`

Download and install the latest uni (and unid if found alongside it), replacing the running binaries in-place.

uni upgrade [--yes]

Flag	Default	Description
`-y`, `--yes`	`false`	Skip confirmation prompt

uni upgrade
# Installed: v0.1.0
# Latest:    v0.1.1
# New version available: v0.1.1
# Upgrade? [y/N] y
# Downloading uni-linux-amd64...
# Downloading unid-linux-amd64...
# Upgraded to v0.1.1.

On Windows, the running binary is renamed to .bak before the new one is placed in its position, since Windows does not allow overwriting a running executable directly. After the upgrade completes successfully, old .bak files are cleaned up automatically.

`uni upgrade check`

Show the installed CLI version and whether a newer one is available, without installing anything.

uni upgrade check

uni upgrade check
# Installed: v0.1.0
# Latest:    v0.1.1
# Update available. Run `uni upgrade` to install v0.1.1.

`uni upgrade list`

List all available CLI versions, newest first. The currently running version is marked with *.

uni upgrade list

uni upgrade list
#   v0.1.1
# * v0.1.0

Compose Commands

See the full Compose Reference for the file format.

`uni compose up`

Start all services defined in a compose file, in dependency order.

uni compose up <compose-file>

Example:

uni compose up stack.yaml
# started backend → a3f8c2d1-...
# started frontend → b4e9d3e2-...

`uni compose down`

Stop all services from a compose file, in reverse dependency order.

uni compose down <compose-file> [--force] [--volumes]

Flag	Default	Description
`--force`	`false`	SIGKILL immediately
`--volumes`	`false`	Remove volumes defined in the compose `volumes:` section

`uni compose ps`

List the state of all services in a compose stack.

uni compose ps <compose-file>

uni compose ps stack.yaml
# SERVICE   ID                                    STATE
# backend   a3f8c2d1-7b4e-4a1f-8c2d-...          running
# frontend  b4e9d3e2-8c5f-5b2g-9d3e-...          running

uni --output json compose ps stack.yaml

`uni compose logs`

Print serial console output for a specific service.

uni compose logs <compose-file> <service>

uni compose logs stack.yaml backend

VM States

created → starting → running → stopping → stopped

State	Description
`created`	VM registered, QEMU not started yet
`starting`	QEMU process being launched
`running`	QEMU process alive and booting/running
`stopping`	Stop signal sent, waiting for process exit
`stopped`	QEMU process has exited

A VM in stopped state can be removed with uni rm. It cannot be restarted — create a new VM with uni run.

When using uni run --attach, the command blocks until the VM reaches the stopped state, streaming all serial console output to stdout during the running state.

CLI Reference

Table of contents

Global Flags

VM Commands

uni run

uni ps

uni logs

uni inspect

uni stop

uni rm

uni cp

uni exec

Image Commands

uni build

uni images

uni rmi

uni push

uni pull

Package Commands

uni pkg list

uni pkg search

uni pkg get

uni pkg remove

Volume Commands

uni volume create

uni volume ls

uni volume inspect

uni volume rm

Kernel Commands

uni kernel check

uni kernel update

uni kernel list

uni kernel use

Upgrade Commands

uni upgrade

uni upgrade check

uni upgrade list

Compose Commands

uni compose up

uni compose down

uni compose ps

uni compose logs

VM States

`uni run`

`uni ps`

`uni logs`

`uni inspect`

`uni stop`

`uni rm`

`uni cp`

`uni exec`

`uni build`

`uni images`

`uni rmi`

`uni push`

`uni pull`

`uni pkg list`

`uni pkg search`

`uni pkg get`

`uni pkg remove`

`uni volume create`

`uni volume ls`

`uni volume inspect`

`uni volume rm`

`uni kernel check`

`uni kernel update`

`uni kernel list`

`uni kernel use`

`uni upgrade`

`uni upgrade check`

`uni upgrade list`

`uni compose up`

`uni compose down`

`uni compose ps`

`uni compose logs`