Skip to main content
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.

​
Step 1: Configure Your First Profile

Profiles store connection details for different Kodexa environments. Start by creating a profile for your environment: 
kdx config set-profile local \
  --url http://localhost:8080 \
  --api-key your-api-key-here
For a production environment: 
kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --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: 
kdx api-resources
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

​
Step 5: Use Different Output Formats

KDX CLI supports multiple output formats for scripting and automation: 
# 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:
workspace.yaml
kind: workspace
name: engineering-workspace
description: Engineering team workspace
metadata:
  team: engineering
  environment: development
Apply the configuration: 
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

​
Configure Multiple Profiles

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-enterprise.com \
  --api-key staging-key

# Production
kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --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

​
Troubleshooting

​
”No active profile configured”

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: 
~/.kodexa/config.yaml
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

Authentication

Configure OAuth login, API keys, and environment variables

Resource Operations

Learn advanced CRUD operations and best practices

Project Commands

Create projects from templates

Store Commands

Upload documents and monitor processing

Document Family Commands

Export extracted data from processed documents

Dynamic API

Discover and execute resource-specific API operations

Metadata Sync

Set up GitOps workflows for infrastructure as code

​
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)

# Extended Commands
kdx project create --template <ref> --org <org> --name <name>  # Create project from template
kdx store upload <store-ref> <file>                            # Upload document
kdx store watch <doc-family-id>                                # Monitor processing
kdx document-family data <doc-family-id>                       # Export extracted data
kdx run <resource-type> [operation]                            # Dynamic API operations