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

# Installation

> Install the KDX CLI on macOS, Linux, or Windows using Homebrew, package managers, or direct binary downloads for the Kodexa AI Platform.

## Installation Options

KDX CLI is distributed through multiple package managers and as direct binary downloads for maximum flexibility.

## Homebrew (macOS/Linux) - Recommended

The easiest way to install and keep KDX CLI up to date on macOS and Linux.

```bash theme={null}
# Add the Kodexa tap
brew tap kodexa-ai/tap

# Install kdx
brew install kdx

# Verify installation
kdx --version
```

### Updating via Homebrew

```bash theme={null}
# Update kdx to the latest version
brew upgrade kdx
```

### Pre-release Builds (Homebrew)

To try the latest development build before it's officially released, install `kdx-dev`. It installs as a separate binary so it can coexist with the stable `kdx`:

```bash theme={null}
# Install the pre-release CLI
brew install kodexa-ai/tap/kdx-dev

# Verify installation
kdx-dev --version

# Update to latest dev build
brew upgrade kdx-dev
```

## Scoop (Windows)

For Windows users, Scoop provides a simple package management experience.

```powershell theme={null}
# Add the Kodexa bucket
scoop bucket add kodexa https://github.com/kodexa-ai/scoop-bucket

# Install kdx
scoop install kdx

# Verify installation
kdx --version
```

### Updating via Scoop

```powershell theme={null}
# Update kdx to the latest version
scoop update kdx
```

### Pre-release Builds (Scoop)

To try the latest development build on Windows, install `kdx-dev`. It installs as a separate binary so it can coexist with the stable `kdx`:

```powershell theme={null}
# Install the pre-release CLI
scoop install kdx-dev

# Verify installation
kdx-dev --version

# Update to latest dev build
scoop update kdx-dev
```

## Docker

Run KDX CLI in a container without installing binaries on your system.

```bash theme={null}
# Pull the latest image
docker pull kodexa/kdx:latest

# Run kdx commands
docker run --rm kodexa/kdx:latest --version

# Mount local files for metadata and document operations
docker run --rm -v $(pwd):/workspace kodexa/kdx:latest get activity-plans

# Create an alias for convenience
alias kdx='docker run --rm -v $(pwd):/workspace -v ~/.kodexa:/root/.kodexa kodexa/kdx:latest'
```

<Note>
  When using Docker, mount `~/.kodexa` to persist your profile configuration across container runs.
</Note>

## Linux Packages

### Debian/Ubuntu (.deb)

```bash theme={null}
# Get the latest version and download the .deb package
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
wget "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_linux_amd64.deb"

# Install with dpkg
sudo dpkg -i "kdx_${VERSION}_linux_amd64.deb"

# Verify installation
kdx --version
```

### Red Hat/Fedora (.rpm)

```bash theme={null}
# Get the latest version and download the .rpm package
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
wget "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_linux_amd64.rpm"

# Install with rpm
sudo rpm -i "kdx_${VERSION}_linux_amd64.rpm"

# Verify installation
kdx --version
```

## Direct Binary Download

Download pre-built binaries from the [GitHub releases page](https://github.com/kodexa-ai/kdx-cli/releases), or use the commands below to automatically fetch the latest version.

### Linux AMD64

```bash theme={null}
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
curl -L "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_linux_x86_64.tar.gz" | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
```

### macOS AMD64 (Intel)

```bash theme={null}
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
curl -L "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_darwin_x86_64.tar.gz" | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
```

### macOS ARM64 (M1/M2/M3)

```bash theme={null}
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
curl -L "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_darwin_arm64.tar.gz" | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
```

### Windows (PowerShell)

```powershell theme={null}
# Get the latest version, download and extract
$release = Invoke-RestMethod -Uri "https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest"
$version = $release.tag_name -replace '^v', ''
Invoke-WebRequest -Uri "https://github.com/kodexa-ai/kdx-cli/releases/download/v${version}/kdx_${version}_windows_x86_64.zip" -OutFile kdx.zip
Expand-Archive kdx.zip -DestinationPath .

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

# Verify installation
kdx --version
```

## Go Install (Development)

For Go developers who want the latest development version:

```bash theme={null}
go install github.com/kodexa-ai/kdx-cli/cmd/kdx@latest
kdx --version
```

## Build from Source (Advanced)

Clone and build from source for custom modifications or contributions.

```bash theme={null}
# Clone the repository
git clone https://github.com/kodexa-ai/kdx-cli
cd kdx-cli

# Build for your platform
make build

# Or install directly to $GOPATH/bin
make install

# Verify installation
kdx --version
```

## Verifying Your Installation

After installation, verify that KDX CLI is working correctly:

```bash theme={null}
# Check version
kdx --version

# View available commands
kdx --help

# Test connection (requires profile setup)
kdx config current-profile
```

## Shell Completion (Optional)

Enable shell completions for a better command-line experience:

### Bash

```bash theme={null}
# Generate completion script
kdx completion bash > /usr/local/etc/bash_completion.d/kdx

# Or add to your .bashrc
echo 'source <(kdx completion bash)' >> ~/.bashrc
source ~/.bashrc
```

### Zsh

```bash theme={null}
# Generate completion script
kdx completion zsh > "${fpath[1]}/_kdx"

# Or add to your .zshrc
echo 'source <(kdx completion zsh)' >> ~/.zshrc
source ~/.zshrc
```

### Fish

```bash theme={null}
kdx completion fish > ~/.config/fish/completions/kdx.fish
```

### PowerShell

```powershell theme={null}
kdx completion powershell | Out-String | Invoke-Expression

# Add to your profile for persistence
kdx completion powershell >> $PROFILE
```

## Upgrading KDX CLI

### Package Manager Upgrades

If you installed via Homebrew or Scoop, use their update commands:

```bash theme={null}
# Homebrew
brew upgrade kdx

# Scoop
scoop update kdx

# Pre-release builds
brew upgrade kdx-dev    # macOS/Linux
scoop update kdx-dev    # Windows
```

### Manual Upgrades

For binary installations, download the latest version and replace the existing binary:

```bash theme={null}
# Backup current version
sudo mv /usr/local/bin/kdx /usr/local/bin/kdx.backup

# Download and install the latest version
VERSION=$(curl -s https://api.github.com/repos/kodexa-ai/kdx-cli/releases/latest | grep '"tag_name"' | sed 's/.*"v\(.*\)".*/\1/')
curl -L "https://github.com/kodexa-ai/kdx-cli/releases/download/v${VERSION}/kdx_${VERSION}_linux_x86_64.tar.gz" | tar xz
sudo mv kdx /usr/local/bin/

# Verify new version
kdx --version
```

## Troubleshooting

### Command Not Found

If `kdx` is not found after installation:

```bash theme={null}
# Check if kdx is in your PATH
which kdx

# If not found, add the installation directory to PATH
export PATH="/usr/local/bin:$PATH"

# Make permanent by adding to shell profile
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
```

### Permission Denied

On Unix-like systems, ensure the binary is executable:

```bash theme={null}
chmod +x /usr/local/bin/kdx
```

### Version Mismatch

Clear the OpenAPI cache if you're experiencing issues after upgrading:

```bash theme={null}
rm -rf ~/.kodexa/cache/
kdx api-resources --refresh
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/guides/kdx-cli/quickstart">
    Configure your first profile and start using KDX CLI
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/kdx-cli/profiles-configuration">
    Learn about profiles and credential management
  </Card>
</CardGroup>