Skip to main content
Early AccessResource types, operations, and validation behavior may change as the platform evolves. The CLI automatically adapts to your platform’s OpenAPI specification.

​
Overview

KDX CLI provides a kubectl-style interface for managing Kodexa platform resources. All operations follow familiar patterns and work with any resource type discovered from your platform’s API.

​
Discovering Resources

​
List Available Resource Types

Before working with resources, discover what’s available in your environment: 
kdx api-resources
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
taxonomies           get, list, create, update, delete
data-forms           get, list, create, update, delete

​
Refresh Resource Discovery

Force a refresh of the OpenAPI cache to discover new resource types: 
kdx api-resources --refresh
Run --refresh after platform upgrades to ensure KDX CLI knows about new resource types.

​
Reading Resources

​
List Resources (GET Multiple)

List all resources of a specific type: 
# List all workspaces
kdx get workspaces

# List all projects
kdx get projects

# List all stores
kdx get stores

​
Get Specific Resource (GET Single)

Retrieve a single resource by name or ID: 
# Get a specific workspace
kdx get workspace my-workspace

# Get a specific project
kdx get project finance-automation

# Get a specific store
kdx get store document-store

​
Describe Resource (Detailed View)

Get comprehensive details about a resource: 
# Describe workspace with all metadata
kdx describe workspace my-workspace

# Describe project with full configuration
kdx describe project finance-automation
The describe command shows:
  • Full resource specification
  • Metadata and labels
  • Related resources
  • Status information
  • Recent events (if available)

​
Output Formats

KDX CLI supports multiple output formats for different use cases.

​
Table Output (Default)

Human-readable table format (default in TTY): 
kdx get workspaces
# or explicitly
kdx get workspaces -o table
Interactive table features:
  • Filter: Press / to filter results
  • Search: Type to search across columns
  • Navigate: PgUp/PgDn, Home/End
  • Refresh: Press r to reload data
  • Edit: Press Enter to edit item
  • Query panel: Press Tab for advanced queries

​
JSON Output

Machine-readable JSON for scripting: 
kdx get workspaces -o json
Use with jq: 
# Extract workspace names
kdx get workspaces -o json | jq '.[].name'

# Filter by status
kdx get workspaces -o json | jq '.[] | select(.status == "active")'

# Get count
kdx get workspaces -o json | jq 'length'

​
YAML Output

Human-readable structured format: 
kdx get workspaces -o yaml
Perfect for:
  • Creating resource templates
  • Reviewing configurations
  • Debugging resource definitions

​
Creating Resources

​
Create from File

Define resources in YAML or JSON files and create them:
workspace.yaml
kind: workspace
name: engineering-workspace
description: Engineering team workspace
metadata:
  team: engineering
  owner: john@example.com
settings:
  maxUsers: 50
  storageQuota: 100GB
Create the resource: 
kdx create workspace -f workspace.yaml

​
Create from JSON

project.json
{
  "kind": "project",
  "name": "invoice-automation",
  "description": "Automated invoice processing",
  "workspace": "engineering-workspace",
  "metadata": {
    "department": "finance"
  }
}

kdx create project -f project.json

​
Create Multiple Resources

Create from a directory or multiple files: 
# Create all resources in a directory
kdx create -f configs/

# Create from multiple files
kdx create -f workspace.yaml -f project.yaml -f store.yaml

​
Pre-Flight Validation

KDX CLI validates resources before sending to the API: 
kdx create workspace -f workspace.yaml
If validation fails, you’ll see detailed errors: 
Error: Validation failed:
  - Field 'name': required field missing
  - Field 'maxUsers': must be >= 1
  - Field 'storageQuota': invalid format, expected <number>GB
Schema validation catches errors early, saving round-trip time to the API.

​
Updating Resources

​
Apply (Create or Update)

The apply command is idempotent - it creates resources that don’t exist and updates those that do: 
# Apply workspace configuration
kdx apply -f workspace.yaml

# Apply will:
# - Create the resource if it doesn't exist
# - Update the resource if it exists
# - Preserve fields not specified in the file

​
Apply from Directory

# Apply all configurations in directory
kdx apply -f configs/

# Recursive apply
kdx apply -f configs/ -R

​
Dry Run (Preview Changes)

Preview what would change without making modifications: 
kdx apply -f workspace.yaml --dry-run
Shows:
  • Resources to be created (marked +)
  • Resources to be updated (marked ~)
  • Fields that would change

​
Deleting Resources

​
Delete by Name

# Delete a workspace
kdx delete workspace old-workspace

# Delete a project
kdx delete project deprecated-project

​
Force Delete (Skip Confirmation)

kdx delete workspace old-workspace --force
Force delete skips confirmation prompts. Use with caution in production environments.

​
Delete from File

Delete resources defined in a file: 
kdx delete -f workspace.yaml

​
Resource Manifests

​
Manifest Structure

All resource manifests follow a common structure: 
kind: <resource-type>        # Required: workspace, project, store, etc.
name: <resource-name>        # Required: unique identifier
description: <description>   # Optional: human-readable description

metadata:                    # Optional: arbitrary key-value pairs
  key1: value1
  key2: value2

# Resource-specific fields
<resource-specific-config>

​
Example: Complete Workspace

kind: workspace
name: data-science-workspace
description: Data science team workspace

metadata:
  team: data-science
  owner: alice@example.com
  environment: production
  cost-center: CC-1234

settings:
  maxUsers: 100
  storageQuota: 500GB
  computeQuota: 200CPU
  enableGPU: true

features:
  - ml-training
  - jupyter-notebooks
  - data-pipelines

security:
  requireMFA: true
  allowedIPRanges:
    - 10.0.0.0/8
    - 192.168.1.0/24

​
Example: Project with References

kind: project
name: invoice-processing
description: Automated invoice document processing

workspace: data-science-workspace

metadata:
  department: finance
  priority: high

assistants:
  - name: invoice-classifier
    model: doc-classifier-v3
    
stores:
  - name: invoice-documents
    type: document-store
  - name: invoice-vectors
    type: vector-store

taxonomies:
  - invoice-fields
  - vendor-categories

​
Best Practices

​
Use Declarative Configuration

Store resource definitions in version control: 
git/
└── kodexa-config/
    ├── workspaces/
    │   ├── engineering.yaml
    │   └── data-science.yaml
    ├── projects/
    │   ├── invoice-automation.yaml
    │   └── document-classification.yaml
    └── stores/
        ├── document-store.yaml
        └── vector-store.yaml

​
Apply Consistently

Use apply instead of create for reproducibility: 
# Good: idempotent, can run multiple times
kdx apply -f configs/

# Avoid: fails if resource exists
kdx create -f configs/

​
Validate Before Committing

Validate manifests before committing to version control: 
# Dry run to check for errors
kdx apply -f new-workspace.yaml --dry-run

# If successful, commit
git add new-workspace.yaml
git commit -m "Add new workspace configuration"

​
Use Metadata for Organization

Add metadata for filtering and organization: 
metadata:
  environment: production
  team: engineering
  cost-center: CC-1234
  managed-by: terraform

​
Document Resource Dependencies

Add comments in YAML to document dependencies: 
kind: project
name: ml-pipeline
# Depends on: data-science-workspace
# References: ml-model-store, training-data-store
workspace: data-science-workspace

​
Advanced Operations

​
Filter Results (JSON)

Use jq for complex filtering: 
# Get all active workspaces
kdx get workspaces -o json | jq '.[] | select(.status == "active")'

# Get workspaces by team
kdx get workspaces -o json | jq '.[] | select(.metadata.team == "engineering")'

# Count resources by type
kdx get projects -o json | jq 'group_by(.workspace) | map({workspace: .[0].workspace, count: length})'

​
Bulk Operations

Process multiple resources: 
# Export all workspaces
kdx get workspaces -o yaml > workspaces-backup.yaml

# Delete all test workspaces
kdx get workspaces -o json | \
  jq -r '.[] | select(.name | startswith("test-")) | .name' | \
  xargs -I {} kdx delete workspace {} --force

​
Template-Based Creation

Use environment variables in manifests: 
kind: workspace
name: ${WORKSPACE_NAME}
description: ${WORKSPACE_DESCRIPTION}

metadata:
  environment: ${ENVIRONMENT}
  owner: ${OWNER_EMAIL}
Process with envsubst: 
export WORKSPACE_NAME="prod-workspace"
export WORKSPACE_DESCRIPTION="Production workspace"
export ENVIRONMENT="production"
export OWNER_EMAIL="ops@example.com"

envsubst < workspace.template.yaml | kdx apply -f -

​
Resource Comparison

Compare configurations between environments: 
# Get production workspace
kdx get workspace my-workspace --profile prod -o yaml > prod.yaml

# Get staging workspace
kdx get workspace my-workspace --profile staging -o yaml > staging.yaml

# Compare
diff prod.yaml staging.yaml

​
Validation Details

​
Schema Validation

KDX CLI validates against OpenAPI schema:
  • Required fields: Must be present
  • Data types: String, number, boolean, array, object
  • Enums: Must match allowed values
  • Patterns: Regex validation for strings
  • Ranges: Min/max values for numbers
  • Format: email, URI, date-time, etc.

​
Validation Error Examples

Missing required field: 
Error: Validation failed for workspace:
  - Field 'name' is required but missing
Invalid data type: 
Error: Validation failed for workspace:
  - Field 'maxUsers': expected integer, got string "fifty"
Enum mismatch: 
Error: Validation failed for project:
  - Field 'status': must be one of: active, inactive, archived
Pattern violation: 
Error: Validation failed for workspace:
  - Field 'name': must match pattern ^[a-z0-9-]+$ (lowercase, numbers, hyphens only)

​
Troubleshooting

​
”Resource type not found”

Refresh the resource discovery: 
kdx api-resources --refresh

​
“Validation failed” errors

Check the OpenAPI schema for your platform: 
# View cached schema
cat ~/.kodexa/cache/openapi.json | jq '.components.schemas'

​
“Resource not found” when it exists

The resource might be in a different workspace or namespace. Check your profile and filters.

​
Changes not taking effect

Clear cache and refresh: 
rm -rf ~/.kodexa/cache/
kdx api-resources --refresh

​
Next Steps

Metadata Sync

Set up GitOps workflows for infrastructure as code

Plugins

Extend CLI with resource-specific operations