Skip to main content
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!
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

OptionDescription
-w, --workerSetup worker after installation
-q, --queue-id <id>Worker queue ID (required with —worker)
-m, --mode <mode>Worker mode: local, docker, daemon (default: local)
-s, --startStart worker immediately after setup
-c, --configInteractive configuration setup
-f, --force-binaryForce binary installation (skip package managers)
-v, --verboseEnable verbose output
-h, --helpShow help message

​
Platform-Specific Installation

​
macOS

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

​
Windows

Download the latest Windows binary from GitHub Releases: 
# 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

​
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

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

​
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