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.
# Add the Kodexa tap
brew tap kodexa-ai/tap
# Install kdx
brew install kdx
# Verify installation
kdx --version
Updating via Homebrew
# Update kdx to the latest version
brew upgrade kdx
Scoop (Windows)
For Windows users, Scoop provides a simple package management experience.
# 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
# Update kdx to the latest version
scoop update kdx
Docker
Run KDX CLI in a container without installing binaries on your system.
# Pull the latest image
docker pull kodexa/kdx:latest
# Run kdx commands
docker run --rm kodexa/kdx:latest --version
# Mount local files for workspace operations
docker run --rm -v $(pwd):/workspace kodexa/kdx:latest get workspaces
# Create an alias for convenience
alias kdx='docker run --rm -v $(pwd):/workspace -v ~/.kodexa:/root/.kodexa kodexa/kdx:latest'
When using Docker, mount ~/.kodexa to persist your profile configuration across container runs.
Linux Packages
Debian/Ubuntu (.deb)
# Download the latest .deb package
wget https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_linux_amd64.deb
# Install with dpkg
sudo dpkg -i kdx_0.1.0_linux_amd64.deb
# Verify installation
kdx --version
Red Hat/Fedora (.rpm)
# Download the latest .rpm package
wget https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_linux_amd64.rpm
# Install with rpm
sudo rpm -i kdx_0.1.0_linux_amd64.rpm
# Verify installation
kdx --version
Direct Binary Download
Download pre-built binaries from the GitHub releases page.
Linux AMD64
curl -L https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_linux_x86_64.tar.gz | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
macOS AMD64 (Intel)
curl -L https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_darwin_x86_64.tar.gz | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
macOS ARM64 (M1/M2/M3)
curl -L https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_darwin_arm64.tar.gz | tar xz
sudo mv kdx /usr/local/bin/
kdx --version
Windows (PowerShell)
# Download and extract
Invoke-WebRequest -Uri "https://github.com/kodexa-ai/kdx-cli/releases/download/v0.1.0/kdx_0.1.0_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:
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.
# 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:
# 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
# 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
# Generate completion script
kdx completion zsh > "${fpath[1]}/_kdx"
# Or add to your .zshrc
echo 'source <(kdx completion zsh)' >> ~/.zshrc
source ~/.zshrc
Fish
kdx completion fish > ~/.config/fish/completions/kdx.fish
PowerShell
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:
# Homebrew
brew upgrade kdx
# Scoop
scoop update kdx
Manual Upgrades
For binary installations, download the new version and replace the existing binary:
# Backup current version
sudo mv /usr/local/bin/kdx /usr/local/bin/kdx.backup
# Download and install new version
curl -L https://github.com/kodexa-ai/kdx-cli/releases/download/v0.2.0/kdx_0.2.0_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:
# 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:
chmod +x /usr/local/bin/kdx
Version Mismatch
Clear the OpenAPI cache if you’re experiencing issues after upgrading:
rm -rf ~/.kodexa/cache/
kdx api-resources --refresh
Next Steps
