> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Kubiya CLI on macOS, Linux, Windows, Docker, or build from source

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

<Tip>
  **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!
</Tip>

<Info>
  **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!
</Info>

## Quick Install (One-Liner) - Recommended

The easiest way to get started on **macOS and Linux**:

```bash theme={null}
# 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)

```bash theme={null}
brew update
brew tap kubiyabot/kubiya
brew install kubiya
```

#### Direct Download

```bash theme={null}
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

<Tabs>
  <Tab title="Automated Script (Recommended)">
    ```bash theme={null}
    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
  </Tab>

  <Tab title="Direct Binary Download">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Specific Version">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

### Windows

Download the latest Windows binary from [GitHub Releases](https://github.com/kubiyabot/cli/releases):

<Tabs>
  <Tab title="PowerShell (Automated)">
    ```powershell theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Manual Download">
    1. Visit [GitHub Releases](https://github.com/kubiyabot/cli/releases)
    2. Download `kubiya-cli-windows-amd64.exe`
    3. Rename to `kubiya.exe`
    4. Move to a directory in your PATH (e.g., `C:\Windows\System32`)
    5. Verify: `kubiya version`
  </Tab>
</Tabs>

## Go Install

If you have Go 1.21+ installed:

```bash theme={null}
go install github.com/kubiyabot/cli@latest

# Verify installation
kubiya version
```

## Build from Source

### Prerequisites

* Go 1.21 or later
* Git
* Make

### Build Steps

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    # Add to ~/.bashrc
    echo 'source <(kubiya completion bash)' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    # Add to ~/.zshrc
    echo 'source <(kubiya completion zsh)' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    kubiya completion fish | source
    # Or add to config
    kubiya completion fish > ~/.config/fish/completions/kubiya.fish
    ```
  </Tab>
</Tabs>

### Configure Environment Variables

```bash theme={null}
# 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"
```

<Info>
  See [Authentication](/cli/authentication) for detailed configuration options.
</Info>

## Docker

Run the CLI in a Docker container:

```bash theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
kubectl exec -it kubiya-cli -n kubiya -- kubiya agent list
```

## Upgrade

### Homebrew

```bash theme={null}
brew update
brew upgrade kubiya
```

### Linux Script

```bash theme={null}
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](https://github.com/kubiyabot/cli/releases).

## Troubleshooting

### Permission Denied

If you encounter permission errors:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# Update CA certificates
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/cli/authentication">
    Configure API keys and connect to the Control Plane
  </Card>

  <Card title="Smart Execution" icon="bolt" href="/cli/exec">
    Execute tasks with automatic planning and on-demand workers
  </Card>

  <Card title="Worker Setup" icon="server" href="/cli/workers">
    Deploy persistent workers for high-frequency tasks
  </Card>

  <Card title="Resource Management" icon="cube" href="/cli/core-resources">
    Manage agents, teams, and all resources
  </Card>
</CardGroup>