Early Access - Installation Methods May ChangeInstallation channels and procedures are subject to change as we approach general availability. Check back regularly for updates or subscribe to release notifications.
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
During the early access phase, upgrades may introduce breaking changes. Review release notes before upgrading production environments.
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
