Install and Configure Omnictl

omnictl is the command-line tool for Omni. It lets you authenticate, manage, and interact with Talos-based Kubernetes clusters through Omni’s centralized API.

Follow the instructions, to install and configure omnictl for your operating system:

Step 1: Install omnictl

You need to install omnictl to use Omni from your terminal.

There are two main ways to do this depending on your setup.

macOS and Linux (recommended)

If you’re on macOS or Linux, the easiest method to install omnictl is through Homebrew.

This command automatically installs and updates omnictl, along with talosctl and the kubectl oidc-login plugin.

brew install siderolabs/tap/sidero-tools

Manual installation

If you prefer a manual setup or aren’t using Homebrew, you can download omnictl directly from the Omni dashboard or from the GitHub releases page:

Omni UI

Navigate to your Omni dashboard and download the binary for your platform.

You’ll receive a binary file named according to your platform and architecture (for example, omnictl-linux-amd64 or omnictl-darwin-arm64).

Once downloaded, rename the file, make it executable, and move it into your system path.

For example, see instructions for your operating system below:

macOs and Linux

On macOS and Linux:

mv omnictl-darwin-arm64 omnictl
chmod +x omnictl
sudo mv omnictl /usr/local/bin/

After this, you’ll be able to run omnictl from any terminal window.

Step 2: Configure omnictl

Next, you’ll configure Omni by adding your omniconfig.yaml file to your to your default configuration directory.

First, download the omniconfig.yaml from your Omni dashboard.

omnictl stores its configuration in the standard directory for your operating system:

• Linux/macOS: Follows the XDG Base Directory Specification.

• Windows: Uses the %LOCALAPPDATA% directory.

OS	Omniconfig Path
Linux	~/.config/omni/config
MacOS	~/Library/Application Support/omni/config
Windows	%LOCALAPPDATA%\omni\config, e.g., C:\Users<USER>\AppData\Local\omni\config

Move or copy the downloaded file to the appropriate path for your OS:

cp omniconfig.yaml <LOCATION_FOR_YOUR_OS_ABOVE>

If you would like to merge the omniconfig.yaml with an existing configuration, use the following command:

omnictl config merge ./omniconfig.yaml

You can confirm that the new configuration was added successfully by listing your contexts with this command:

Command

omnictl config contexts

Step 3: Authenticate and verify

Once installed and configured, the last step is authentication. This connects your local CLI to your Omni account.

Run the following command to trigger authentication:

omnictl get clusters

A browser window should open automatically for sign-in. If it doesn’t, copy and paste the URL manually:

BROWSER=echo omnictl get clusters

After you complete the sign-in, your credentials are cached locally, and you can start managing your clusters with omnictl.