CLI Reference

Install omnideck from the terminal and use the commands available in the current standalone CLI.

The omnideck CLI sets up and manages the same local omnideck runtime as the desktop app. It uses Podman on Windows, macOS, and Linux; other container runtimes are not supported.

Running omnideck without a subcommand opens the appropriate interactive screen for first setup, runtime preparation, repair, or managing an existing installation.

The commands below apply to the published v0.10.0 stable and v0.11.0-beta.8 preview releases. Run omnideck --version to check the build installed on your computer.

Install the CLI

Choose a release

On macOS or Linux, choose the v0.10.0 stable release or v0.11.0-beta.8 preview. On Windows, use v0.11.0-beta.8: v0.10.0 can stall at Start omnideck while checking the runtime network. The current desktop app includes v0.11.0-beta.6. Download both your archive and SHA256SUMS from the same release.

On macOS, check Apple menu → About This Mac: Chip means Apple silicon, and an Intel Processor means x86-64. On Linux, uname -m reports x86_64 or aarch64. On Windows, check Settings → System → About → System type.

macOS or Linux archive

Open a terminal in the download folder. First calculate the archive's SHA-256 fingerprint and compare it with the line for that file in SHA256SUMS. For example:

# macOS, Apple silicon
shasum -a 256 omnideck-darwin-arm64.tar.gz

# Linux, x86-64
sha256sum omnideck-linux-amd64.tar.gz

After the fingerprint matches, extract your archive. Use the filename for your computer from the table above:

# macOS, Apple silicon
tar -xzf omnideck-darwin-arm64.tar.gz

# Linux, x86-64
tar -xzf omnideck-linux-amd64.tar.gz

Run only the extraction command for your computer. Then install the extracted binary and check its version:

sudo mkdir -p /usr/local/bin
sudo install -m 755 omnideck /usr/local/bin/omnideck
omnideck --version

/usr/local/bin must be on your PATH. If omnideck --version still reports an older build, run command -v omnideck to see which copy your shell finds, and place /usr/local/bin ahead of an older Homebrew installation in PATH. The sudo commands copy the CLI into a system directory; run omnideck itself as your normal user.

On macOS, the v0.11.0-beta.8 executable is signed with omnideck’s Apple Developer ID and notarized by Apple. The first time it runs, macOS may check it with Apple online, so stay connected to the internet for that first run.

Windows archive

Download your Windows archive and SHA256SUMS from v0.11.0-beta.8. This is a preview release; the stable v0.10.0 has a separate Windows startup issue described above. The Windows executable is not signed yet, so Windows may warn about an unknown publisher; continue only when the archive's hash matches SHA256SUMS. If startup fails with a memory.max error on WSL 3.0.1 and Podman 6.0.2, use the tested WSL recovery steps. This issue is not fixed in beta.8. Beta.7 added a link to these steps when the CLI detects the failure; the CLI does not change WSL settings.

Open PowerShell in the download folder. For x86-64, verify the archive:

Get-FileHash .\omnideck-windows-amd64.zip -Algorithm SHA256

Compare the hash with the line for that file in SHA256SUMS; letter case does not matter. On ARM64, use omnideck-windows-arm64.zip instead. After the hash matches, extract it into your user account:

Expand-Archive .\omnideck-windows-amd64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\omnideck-cli" -Force
& "$env:LOCALAPPDATA\Programs\omnideck-cli\omnideck.exe" --version

Use the ARM64 archive filename in Expand-Archive on an ARM-based PC. To make omnideck available by name, search Windows for Edit environment variables for your account, edit your user Path, and add %LOCALAPPDATA%\Programs\omnideck-cli. Open a new PowerShell window and run omnideck --version.

Homebrew on macOS or Linux

The Homebrew tap currently installs v0.9.0, an older CLI. It does not include the --json, runtime, or environment commands documented below, and its setup can offer Docker. Use a release archive above for the current Podman setup and command reference.

If you specifically want the Homebrew version:

brew tap omnideck-dev/tap
brew install omnideck-dev/tap/omnideck
omnideck --version

If Homebrew reports that the tap is untrusted, review the official omnideck formula, trust that formula, and retry:

brew trust --formula omnideck-dev/tap/omnideck
brew install omnideck-dev/tap/omnideck
omnideck --version

The trust step is conditional: older Homebrew versions may not ask for it.

brew upgrade omnideck upgrades only as far as the version published in the tap; it does not install a preview release.

Run omnideck as your normal user. Do not put sudo before it or choose Run as administrator; guided setup asks the operating system for approval only when a system change requires it.

First run

omnideck

The first run prepares Podman when needed and guides you through creating the first omnideck installation. When setup finishes:

omnideck doctor
omnideck status

The local browser address is normally http://localhost:2337 and is also shown by omnideck list and omnideck status.

Commands

Setup and everyday management

Saved configuration

Supported keys for config set are home_volume, state_volume, memory, shm_size, web_ui_port, and image. Apply a changed setting by running omnideck update for that instance; a simple restart does not recreate the container with new settings.

Runtime and automation

environment ensure requires --name and accepts --image, --port, --memory, --shm-size, --home-volume, and --state-volume. It is primarily an integration surface for the desktop app and automation; interactive users normally use bare omnideck or omnideck add.

Global flags

Run omnideck --version to print the version, commit, and build date. --version belongs to the root command rather than every subcommand.

Every command also accepts -h or --help.

--json also selects the non-interactive path for commands that support one. When more than one instance exists, non-interactive commands require --name instead of opening a picker.

Command-specific flags

add

The global --name flag sets the new instance name when used with add.

update

logs

Use --follow=false for a finite plain-text log read. In JSON mode, following defaults to false unless you explicitly pass --follow.

remove NAME

Non-interactive removal requires exactly one of --keep-volumes or --delete-volumes. Deleting volumes also requires exactly one of --backup or --no-backup.

Examples

# Create another instance interactively
omnideck add

# List every saved instance
omnideck list

# Inspect and manage a specific instance
omnideck --name omnideck2 status
omnideck --name omnideck2 stop
omnideck --name omnideck2 start

# Follow logs, starting with the latest 100 lines
omnideck --name omnideck2 logs --tail 100

# Run health checks
omnideck --name omnideck2 doctor

# Change a setting, then recreate safely to apply it
omnideck --name omnideck2 config set memory 4g
omnideck --name omnideck2 update

# Create an instance without a TUI
omnideck add --plain --name staging --port 2338

# Remove an instance interactively
omnideck remove staging

Multiple instances

omnideck add creates one additional instance with its own name, browser port, home volume, and state volume. omnideck list shows all saved instances.

Commands that act on one instance open a picker when more than one exists. Pass --name to select directly. Scripts and JSON callers must pass --name; the CLI never opens a picker without an interactive terminal.

Configuration

Configuration files

Instance files live under the platform's conventional configuration directory:

Each instance is stored at instances/<name>.yaml. The shared Podman choice is stored separately in settings.yaml.

container_name: omnideck
layout_version: 1
home_volume: omnideck-home
state_volume: omnideck-state
memory: 2g
shm_size: 1024m
web_ui_port: "2337"
image: ghcr.io/omnideck-dev/omnideck:latest
installed_at: 2026-08-16T12:00:00Z

The home and state values are Podman volume names, not host directory paths. The home volume holds user-visible working files; the state volume holds application state. omnideck remove keeps both unless you explicitly choose permanent deletion.

Memory limits

Guided setup suggests a container memory limit based on the computer's total RAM, from 1 GB on smaller systems up to 6 GB on larger ones. Shared memory defaults to half of the container limit. On macOS, the container limit also stays below the memory assigned to the Podman machine.

These limits apply to the omnideck container, not to Ollama or another model server running separately on the host. Check the requirements of any local model you plan to use.

Change the limits, then recreate the container safely to apply them:

omnideck config set memory 4g
omnideck config set shm_size 2g
omnideck update

Build from source

Building v0.11.0-beta.8 requires Go 1.26.9 or newer, as set in its go.mod. Other versions list their own minimum in go.mod. To build that release, check out its tag:

git clone https://github.com/omnideck-dev/cli
cd cli
git checkout v0.11.0-beta.8
go build -trimpath -o omnideck .

Run ./omnideck --version, then move the binary to a directory on your PATH if you want it available system-wide.