Installation

The Kubiya CLI is available for multiple platforms and can be installed using package managers or direct download.

On-Demand Execution: Run AI tasks without needing a queue in advance - perfect for CI/CD pipelines! Just use kubiya exec "your task" and the Control Plane creates an ephemeral worker queue, provisions a worker on managed infrastructure, runs your task, and automatically cleans up. No queue setup needed!

Worker Flexibility: If you want to run persistent workers, they can run on nearly any compute environment - your local machine (Mac, Linux, Windows), Kubernetes clusters, Docker containers, VMs (EC2, GCE, Azure), or bare metal servers. This makes them incredibly powerful and easy to deploy wherever your infrastructure lives!

Quick Install (One-Liner) - Recommended

The easiest way to get started on macOS and Linux:

# Basic installation
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

# Install + configure worker in one command
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash -s -- --worker --queue-id=my-queue

# Install + start worker in daemon mode (production)
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash -s -- --worker --queue-id=prod-queue --mode=daemon --start

# Interactive configuration
curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash -s -- --config

Install Script Options

Option	Description
`-w, --worker`	Setup worker after installation
`-q, --queue-id <id>`	Worker queue ID (required with —worker)
`-m, --mode <mode>`	Worker mode: local, docker, daemon (default: local)
`-s, --start`	Start worker immediately after setup
`-c, --config`	Interactive configuration setup
`-f, --force-binary`	Force binary installation (skip package managers)
`-v, --verbose`	Enable verbose output
`-h, --help`	Show help message

Platform-Specific Installation

macOS

Homebrew (Recommended)

brew update
brew tap kubiyabot/kubiya
brew install kubiya

Direct Download

VERSION=v2.5.5
curl -LO "https://github.com/kubiyabot/cli/releases/download/${VERSION}/kubiya-cli-darwin-arm64"
chmod +x kubiya-cli-darwin-arm64
sudo mv kubiya-cli-darwin-arm64 /usr/local/bin/kubiya

Linux

Automated Script (Recommended)
Direct Binary Download
Specific Version

curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

The script automatically detects your Linux distribution and installs using:

Debian/Ubuntu: APT package manager
RHEL/CentOS/Fedora: YUM/DNF package manager
Other: Direct binary installation

# Download latest release for your architecture
VERSION=$(curl -s https://api.github.com/repos/kubiyabot/cli/releases/latest | grep tag_name | cut -d '"' -f 4)
ARCH=$(uname -m | sed 's/x86_64/amd64/g' | sed 's/aarch64/arm64/g')

curl -LO "https://github.com/kubiyabot/cli/releases/download/${VERSION}/kubiya-cli-linux-${ARCH}"
chmod +x kubiya-cli-linux-${ARCH}
sudo mv kubiya-cli-linux-${ARCH} /usr/local/bin/kubiya

# Verify installation
kubiya version

VERSION=v2.5.5
ARCH=$(uname -m | sed 's/x86_64/amd64/g' | sed 's/aarch64/arm64/g')
curl -LO "https://github.com/kubiyabot/cli/releases/download/${VERSION}/kubiya-cli-linux-${ARCH}"
chmod +x kubiya-cli-linux-${ARCH}
sudo mv kubiya-cli-linux-${ARCH} /usr/local/bin/kubiya

Windows

Download the latest Windows binary from GitHub Releases:

PowerShell (Automated)
Manual Download

# Using PowerShell
$VERSION = (Invoke-WebRequest -Uri "https://api.github.com/repos/kubiyabot/cli/releases/latest" | ConvertFrom-Json).tag_name
$URL = "https://github.com/kubiyabot/cli/releases/download/$VERSION/kubiya-cli-windows-amd64.exe"
Invoke-WebRequest -Uri $URL -OutFile "kubiya.exe"

# Move to a directory in your PATH
Move-Item kubiya.exe C:\Windows\System32\kubiya.exe

# Verify installation
kubiya version

Visit GitHub Releases
Download kubiya-cli-windows-amd64.exe
Rename to kubiya.exe
Move to a directory in your PATH (e.g., C:\Windows\System32)
Verify: kubiya version

Go Install

If you have Go 1.21+ installed:

go install github.com/kubiyabot/cli@latest

# Verify installation
kubiya version

Build from Source

Prerequisites

Go 1.21 or later
Git
Make

Build Steps

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

# Build the binary
make build

# Install locally
make install

# Verify installation
kubiya version

Development Build

# Build with race detection
make build-race

# Run tests
make test

# Build for multiple platforms
make build-all

Verify Installation

After installation, verify that the CLI is working correctly:

# Check version
kubiya version

# Verify help is accessible
kubiya --help

# Test with a simple command (requires API key)
export KUBIYA_API_KEY="your-api-key"
kubiya agent list

Expected output:

Kubiya CLI v2.5.5
Build: 2024-11-21
Commit: abc123def

Post-Installation Setup

Enable Shell Completion

Bash
Zsh
Fish

# Add to ~/.bashrc
echo 'source <(kubiya completion bash)' >> ~/.bashrc
source ~/.bashrc

# Add to ~/.zshrc
echo 'source <(kubiya completion zsh)' >> ~/.zshrc
source ~/.zshrc

kubiya completion fish | source
# Or add to config
kubiya completion fish > ~/.config/fish/completions/kubiya.fish

Configure Environment Variables

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export KUBIYA_API_KEY="your-api-key"
export KUBIYA_BASE_URL="https://api.kubiya.ai/api/v1"

See Authentication for detailed configuration options.

Docker

Run the CLI in a Docker container:

# Pull the latest image
docker pull kubiyabot/cli:latest

# Run CLI commands
docker run --rm -e KUBIYA_API_KEY="your-api-key" kubiyabot/cli:latest version

# Interactive mode
docker run -it --rm -e KUBIYA_API_KEY="your-api-key" kubiyabot/cli:latest

# Run with volume mount for persistent config
docker run -it --rm \
  -e KUBIYA_API_KEY="your-api-key" \
  -v ~/.kubiya:/root/.kubiya \
  kubiyabot/cli:latest

# Create an alias for convenience
alias kubiya='docker run --rm -e KUBIYA_API_KEY="$KUBIYA_API_KEY" kubiyabot/cli:latest'

Kubernetes Installation

Deploy the CLI as a pod in your Kubernetes cluster:

apiVersion: v1
kind: Pod
metadata:
  name: kubiya-cli
  namespace: kubiya
spec:
  containers:
  - name: cli
    image: ghcr.io/kubiyabot/kubiya-cli:latest
    command: ["sleep", "infinity"]
    env:
    - name: KUBIYA_API_KEY
      valueFrom:
        secretKeyRef:
          name: kubiya-secrets
          key: api-key

Execute commands:

kubectl exec -it kubiya-cli -n kubiya -- kubiya agent list

Upgrade

Homebrew

brew update
brew upgrade kubiya

Linux Script

curl -fsSL https://raw.githubusercontent.com/kubiyabot/cli/main/install.sh | bash

Manual Upgrade

Download and replace the binary with the latest version from the releases page.

Troubleshooting

Permission Denied

If you encounter permission errors:

# Make binary executable
chmod +x /path/to/kubiya

# Move to a directory in PATH
sudo mv kubiya /usr/local/bin/

Command Not Found

Ensure /usr/local/bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

SSL/TLS Errors

If you encounter certificate errors:

# Update CA certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

Next Steps

Authentication

Configure API keys and connect to the Control Plane

Smart Execution

Execute tasks with automatic planning and on-demand workers

Worker Setup

Deploy persistent workers for high-frequency tasks

Resource Management

Manage agents, teams, and all resources

Getting Started

On-Demand Execution

Control Plane

Control Plane Resources

Context Graph

Cognitive Memory

Advanced

Quick Install (One-Liner) - Recommended

Install Script Options

Platform-Specific Installation

macOS

Homebrew (Recommended)

Direct Download

Linux

Windows

Go Install

Build from Source

Prerequisites

Build Steps

Development Build

Verify Installation

Post-Installation Setup

Enable Shell Completion

Configure Environment Variables

Docker

Kubernetes Installation

Upgrade

Homebrew

Linux Script

Manual Upgrade

Troubleshooting

Permission Denied

Command Not Found

SSL/TLS Errors

Next Steps

Authentication

Smart Execution

Worker Setup

Resource Management

​Quick Install (One-Liner) - Recommended

​Install Script Options

​Platform-Specific Installation

​macOS

​Homebrew (Recommended)

​Direct Download

​Linux

​Windows

​Go Install

​Build from Source

​Prerequisites

​Build Steps

​Development Build

​Verify Installation

​Post-Installation Setup

​Enable Shell Completion

​Configure Environment Variables

​Docker

​Kubernetes Installation

​Upgrade

​Homebrew

​Linux Script

​Manual Upgrade

​Troubleshooting

​Permission Denied

​Command Not Found

​SSL/TLS Errors

​Next Steps

Authentication

Smart Execution

Worker Setup

Resource Management

Quick Install (One-Liner) - Recommended

Install Script Options

Platform-Specific Installation

macOS

Homebrew (Recommended)

Direct Download

Linux

Windows

Go Install

Build from Source

Prerequisites

Build Steps

Development Build

Verify Installation

Post-Installation Setup

Enable Shell Completion

Configure Environment Variables

Docker

Kubernetes Installation

Upgrade

Homebrew

Linux Script

Manual Upgrade

Troubleshooting

Permission Denied

Command Not Found

SSL/TLS Errors

Next Steps