Skip to main content

​
KDX CLI Quick Start

The KDX CLI (kdx) is a modern, kubectl-style command-line interface for the Kodexa AI Platform. It provides a powerful and familiar interface for managing Kodexa resources directly from the terminal.

​
Why KDX CLI?

  • Kubectl-Style Interface: Familiar commands like get, describe, create, apply, and delete
  • Dynamic Resource Discovery: Automatically discovers resources from your platform’s OpenAPI specification
  • Profile-Based Authentication: Manage multiple environments with ease
  • Production Safety: Confirmation prompts prevent accidental changes to production
  • GitOps Ready: Built-in metadata sync for version-controlled infrastructure
  • Multiple Output Formats: Interactive tables, JSON, and YAML for any workflow

​
Installation

# Add the Kodexa tap
brew tap kodexa-ai/tap

# Install kdx
brew install kdx

# Verify installation
kdx --version

​
Scoop (Windows)

# Add the Kodexa bucket
scoop bucket add kodexa https://github.com/kodexa-ai/scoop-bucket

# Install kdx
scoop install kdx

# Verify installation
kdx --version

​
Other Installation Methods

See the full installation guide for Docker, direct binary downloads, and building from source.

​
Quick Start

​
1. Configure Authentication

Recommended: Environment Variables Set environment variables for your Kodexa environments: 
export KODEXA_URL="https://platform.kodexa-enterprise.com"
export KODEXA_ACCESS_TOKEN="your-api-key-here"
Add these to your shell profile (~/.bashrc, ~/.zshrc) to make them permanent. Alternative: Profiles You can also use profiles for managing multiple environments: 
kdx config set-profile local \
  --url http://localhost:8080 \
  --api-key your-api-key-here
For production (with safety prompts): 
kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --api-key your-production-api-key \
  --production
The --production flag enables confirmation prompts before destructive operations to prevent accidental changes.

​
2. Discover Resources

See what resources are available in your environment: 
kdx api-resources

​
3. List Resources

Use the get command to list resources: 
# List all workspaces
kdx get workspaces

# List all projects
kdx get projects

# List all stores
kdx get stores

​
4. Get Specific Resources

Retrieve details about a specific resource: 
kdx get workspace my-workspace
kdx describe workspace my-workspace

​
5. Create Resources

Create resources declaratively using YAML files:
workspace.yaml
kind: workspace
name: engineering-workspace
description: Engineering team workspace
Apply the configuration: 
kdx create workspace -f workspace.yaml

​
Working with Multiple Environments

Switch between profiles easily: 
# Switch to staging
kdx config use-profile staging

# Use production profile for a single command
kdx get workspaces --profile prod

​
Output Formats

KDX CLI supports multiple output formats: 
# Interactive table (default for terminals)
kdx get workspaces

# JSON output (great for scripting)
kdx get workspaces -o json

# YAML output
kdx get workspaces -o yaml

​
Getting Help

KDX CLI has built-in help for every command: 
# General help
kdx --help

# Command-specific help
kdx get --help
kdx config --help

​
Configuration

All KDX CLI configuration is stored in ~/.kodexa/config.yaml. The CLI now enforces secure defaults (config directory 0700, file 0600) so API keys are readable only by your user. Keep keys out of shell history and prefer profiles or environment variables over inlining secrets in commands.

​
Validation & Safety

  • Requests sent via apply and run are validated against the live OpenAPI schema before they reach the API, catching missing/invalid fields early.
  • Production-marked profiles prompt before destructive actions; use --skip-production-confirm only for trusted automation.
  • Module applies package implementation files into a temporary ZIP (unique per run) to avoid overwriting local files; the archive is cleaned up automatically.

​
Plugins

Resource-specific plugins are registered automatically—no separate kdx plugins command is required. Current built-ins:
  • kdx project create --template <tpl> --org <org> --name <name> to spin up projects from templates.

​
Next Steps

Full KDX CLI Guide

Learn about all KDX CLI capabilities and features

Installation Guide

Comprehensive installation options for all platforms

Profile Configuration

Deep dive into profile management

Resource Operations

Learn advanced CRUD operations