Early AccessCommands and workflows shown here are subject to change as we refine the CLI based on user feedback.
Prerequisites
Before you begin, ensure you have:
- KDX CLI installed (installation guide)
- Access to a Kodexa platform instance
- An API key from your Kodexa account
You can generate an API key from your Kodexa platform account settings.
kdx config set-profile local \
--url http://localhost:8080 \
--api-key your-api-key-here
kdx config set-profile prod \
--url https://platform.kodexa.ai \
--api-key your-production-api-key
Verify Your Profile
Check that your profile was created successfully:
# Show current active profile
kdx config current-profile
# List all configured profiles
kdx config list-profiles
Step 2: Discover Available Resources
KDX CLI dynamically discovers resources from your platform’s OpenAPI specification:
This command displays all available resource types (workspaces, projects, stores, etc.) and their supported operations.
Example output:
RESOURCE OPERATIONS
workspaces get, list, create, update, delete
projects get, list, create, update, delete
stores get, list, create, update, delete
assistants get, list, create, update, delete
Step 3: List Resources
Use the get command to list resources of any type:
# List all workspaces
kdx get workspaces
# List all projects
kdx get projects
# List all stores
kdx get stores
Interactive Table View
When running in a terminal (TTY), kdx get launches an interactive table interface with:
- Server-side paging for large result sets
- Inline filtering - Press
/ to filter
- Multi-line query panel - Press
Tab to open
- Navigation -
PgUp/PgDn, Home/End
- Refresh - Press
r to refresh data
- Edit - Press
Enter to edit an item
Step 4: Get Specific Resources
Retrieve details about a specific resource:
# Get a specific workspace
kdx get workspace my-workspace
# Get a specific project
kdx get project my-project
# Get a specific store
kdx get store my-store
# JSON output (great for scripting)
kdx get workspaces -o json
# YAML output (human-readable)
kdx get workspaces -o yaml
# Table output (default for terminals)
kdx get workspaces -o table
Using JSON Output with jq
# Extract specific fields
kdx get workspaces -o json | jq '.[].name'
# Filter results
kdx get workspaces -o json | jq '.[] | select(.status == "active")'
Step 6: Describe Resources
Get detailed information about a resource:
# Describe a workspace with full details
kdx describe workspace my-workspace
# Describe a project
kdx describe project my-project
Step 7: Create Resources from Files
Create resources declaratively using YAML files:
Create a Workspace
Create a file named workspace.yaml:
kind: workspace
name: engineering-workspace
description: Engineering team workspace
metadata:
team: engineering
environment: development
kdx create workspace -f workspace.yaml
Apply Changes (Create or Update)
Use apply to create a resource if it doesn’t exist, or update it if it does:
kdx apply -f workspace.yaml
The apply command is idempotent - you can run it multiple times safely.
Step 8: Delete Resources
Remove resources when no longer needed:
# Delete a workspace
kdx delete workspace old-workspace
# Force delete (skip confirmation)
kdx delete workspace old-workspace --force
Working with Multiple Environments
Set up profiles for each environment:
# Local development
kdx config set-profile local \
--url http://localhost:8080 \
--api-key local-dev-key
# Staging
kdx config set-profile staging \
--url https://staging.kodexa.ai \
--api-key staging-key
# Production
kdx config set-profile prod \
--url https://platform.kodexa.ai \
--api-key production-key
Switch Between Profiles
# Switch to staging
kdx config use-profile staging
# Verify current profile
kdx config current-profile
# Switch to production
kdx config use-profile prod
Use a Specific Profile for One Command
Override the active profile for a single command:
# Use production profile for this command only
kdx get workspaces --profile prod
# Use staging profile
kdx get projects --profile staging
Using Plugin Commands
KDX CLI includes plugins that extend functionality for specific resources:
Workspace Operations
# Check workspace status
kdx workspace status my-workspace
# Execute a command in a workspace
kdx workspace exec my-workspace "rebuild-index"
Store Operations
# View store statistics
kdx store stats my-store
# Trigger store reindexing
kdx store reindex my-store
# Force reindex even if already running
kdx store reindex my-store --force
Troubleshooting
Create a profile first:
kdx config set-profile local --url http://localhost:8080 --api-key your-key
“Authentication failed”
Check your profile settings and API key:
# View current profile
kdx config current-profile
# Update API key if needed
kdx config set-profile local --url http://localhost:8080 --api-key new-key
“Resource type not found”
Refresh the resource cache:
kdx api-resources --refresh
Resources Seem Outdated
Clear the cache and refresh:
rm -rf ~/.kodexa/cache/
kdx api-resources --refresh
Configuration File Location
All KDX CLI configuration is stored in:
Resource cache:
~/.kodexa/cache/openapi.json
Getting Help
KDX CLI has built-in help for every command:
# General help
kdx --help
# Command-specific help
kdx get --help
kdx config --help
kdx apply --help
kdx workspace --help
# Show version
kdx version
Next Steps
Quick Reference
# Profile management
kdx config set-profile <name> --url <url> --api-key <key>
kdx config use-profile <name>
kdx config current-profile
kdx config list-profiles
# Resource operations
kdx api-resources # Discover available resources
kdx get <resource-type> # List resources
kdx get <resource-type> <name> # Get specific resource
kdx describe <resource-type> <name> # Detailed resource info
kdx create <resource-type> -f file # Create from file
kdx apply -f file # Create or update
kdx delete <resource-type> <name> # Delete resource
# Output formats
kdx get <resource-type> -o json # JSON output
kdx get <resource-type> -o yaml # YAML output
kdx get <resource-type> -o table # Table output (default)
# Plugins
kdx workspace status <name> # Workspace status
kdx workspace exec <name> <cmd> # Execute command
kdx store stats <name> # Store statistics
kdx store reindex <name> # Reindex store
