Resource Operations - Kodexa Developer Portal

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

Production Environment Safety

When working with production environments, KDX CLI provides additional safety measures to prevent accidental changes. This applies whether you’re using profiles or environment variable configuration.

Production Confirmation Prompts

Operations that can modify or delete resources will prompt for confirmation when using a production environment: Creating resources (profile-based):

kdx create workspace new-workspace --profile prod

Creating resources (environment-based):

kdx create workspace new-workspace --env prod

Prompt:

⚠️  This action may make changes.
Environment 'prod' is marked as a production environment.
Proceed with creating workspace? [y/N]:

Applying configurations:

kdx apply -f workspace.yaml --profile prod
# or
kdx apply -f workspace.yaml --env prod

Deleting resources:

kdx delete workspace old-workspace --profile prod
# or
kdx delete workspace old-workspace --env prod

Affected Operations

The following operations trigger production confirmations:

kdx create - Creating new resources
kdx apply - Applying resource configurations (create or update)
kdx delete - Deleting resources
kdx sync deploy - Deploying metadata to production

Bypassing Confirmations (CI/CD)

For automation pipelines, use --skip-production-confirm:

# CI/CD deployment script
kdx apply -f resources/ --profile prod --skip-production-confirm
# or
kdx apply -f resources/ --env prod --skip-production-confirm

The --skip-production-confirm flag logs a warning message for audit trails. Use only in trusted automation contexts.

Read-Only Operations

These operations never trigger confirmations as they don’t modify resources:

kdx get - Listing resources
kdx describe - Viewing resource details
kdx api-resources - Discovering resource types

Profile-based (legacy):

kdx config set-profile prod --url https://platform.kodexa.ai --api-key key --production

Environment-based (recommended):

# Set KODEXA_PRODUCTION=true in your environment configuration
export KODEXA_PRODUCTION=true
export KODEXA_URL=https://platform.kodexa.ai
export KODEXA_ACCESS_TOKEN=your-token

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: Using profiles:

# 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

Using environment variables:

# Get production workspace
kdx get workspace my-workspace --env prod -o yaml > prod.yaml

# Get staging workspace
kdx get workspace my-workspace --env 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

Module Deployment

Overview

Modules are a special type of resource that can include both metadata (configuration) and implementation (code). The apply command automatically detects implementation configuration in module metadata and uploads the code—no separate deploy step needed.

Module YAML Structure

A complete module definition includes:

type: module
name: my-document-processor
description: Custom document processing module

metadata:
  # Implementation configuration
  contents:
    - "src/**/*.py"           # Include all Python files in src/
    - "requirements.txt"      # Include dependencies
    - "README.md"            # Include documentation

  ignoredContents:
    - "**/__pycache__/**"    # Exclude Python cache
    - "**/*.pyc"             # Exclude compiled Python
    - "**/tests/**"          # Exclude tests
    - "**/.env"              # Exclude environment files

# Module-specific configuration
runtime: python
version: "1.0.0"

Automatic Implementation Upload

When you run kdx apply -f module.yml, the CLI:

Creates/updates the module metadata in the platform
Detects implementation configuration (if metadata.contents exists)
Finds matching files using the glob patterns
Builds a ZIP archive with all matched files
Uploads the implementation to the platform
Cleans up the temporary ZIP file

All in one command—no separate deployment step required.

File Pattern Configuration

Contents Patterns

The contents field accepts glob patterns to specify which files to include:

metadata:
  contents:
    # Include specific directories
    - "src/**/*.py"

    # Include specific files
    - "requirements.txt"
    - "README.md"
    - "config.json"

    # Include all files of a type
    - "**/*.py"
    - "**/*.json"

Ignored Patterns

The ignoredContents field excludes files even if they match contents patterns:

metadata:
  ignoredContents:
    # Common Python excludes
    - "**/__pycache__/**"
    - "**/*.pyc"
    - "**/.pytest_cache/**"

    # Development files
    - "**/.env"
    - "**/.venv/**"
    - "**/tests/**"

    # Version control
    - "**/.git/**"
    - "**/.gitignore"

Complete Module Example

module.yml

type: module
name: invoice-extractor
slug: invoice-extractor
orgSlug: acme-corp
description: ML-powered invoice data extraction

metadata:
  version: "2.1.0"
  author: "Data Team"

  # Implementation upload configuration
  contents:
    - "src/**/*.py"
    - "models/**/*.pkl"
    - "requirements.txt"
    - "README.md"

  ignoredContents:
    - "**/__pycache__/**"
    - "**/*.pyc"
    - "**/tests/**"
    - "**/.env"

# Module runtime configuration
runtime: python
pythonVersion: "3.11"
entrypoint: "src/main.py"

Deploying a Module

From the directory containing your module.yml:

# Apply creates/updates metadata AND uploads implementation
kdx apply -f module.yml

Output:

🚀 Applying module: invoice-extractor

📝 Updating module...
   ✓ Resolved to ID: 12345

✅ module updated successfully: invoice-extractor

   Ref: module://acme-corp/invoice-extractor
   ID:  12345

📦 Module includes implementation configuration
   Patterns: [src/**/*.py models/**/*.pkl requirements.txt README.md]

📂 Finding files in /path/to/project...
   Found 23 files
     • src/main.py
     • src/extractors/invoice.py
     • src/models/classifier.py
     • models/trained_model.pkl
     ... and 19 more

📦 Building ZIP archive: implementation.zip
   Packaged 23 files (2.34 MB)

⬆️  Uploading to server...
   ✅ Upload successful

🧹 Cleaning up...
   Deleted implementation.zip

Module Workflow Examples

New Module (First Deployment)

# 1. Create module YAML
cat > model.yml << 'EOF'
type: module
name: my-processor
description: Custom processor
metadata:
  contents:
    - "src/**/*.py"
    - "requirements.txt"
EOF

# 2. Apply (creates + uploads)
kdx apply -f model.yml

Update Existing Module

# Make code changes
vim src/main.py

# Apply again (updates metadata + re-uploads code)
kdx apply -f model.yml

The same command works for both creation and updates.

Module Without Implementation

If your module YAML doesn’t include metadata.contents, only the metadata is updated:

type: module
name: config-only-module
description: Metadata-only configuration
# No metadata.contents field

kdx apply -f module.yml
# Only updates metadata, no upload

Production Workflow

Using profiles:

# Test in development
kdx apply -f module.yml --profile dev

# Deploy to production (with confirmation)
kdx apply -f module.yml --profile prod
# Prompts: "Proceed with applying module? [y/N]"

Using environment variables:

# Test in development
kdx apply -f module.yml --env dev

# Deploy to production (with confirmation)
kdx apply -f module.yml --env prod
# Prompts: "Proceed with applying module? [y/N]"

Troubleshooting

No Files Found

Error: no files found matching the patterns

Cause: Glob patterns don’t match any files in the directory Fix:

Verify patterns match your project structure
Check you’re running from the correct directory
Use absolute paths if needed

# Bad: Wrong directory structure
contents:
  - "lib/**/*.py"  # But code is in src/

# Good: Matches actual structure
contents:
  - "src/**/*.py"

Upload Failed

⚠️  Warning: Module metadata updated but implementation upload failed
   You can retry by running: kdx apply -f <your-module.yml> again

Cause: Network issue, permission problem, or server error Fix: Simply re-run the same command:

kdx apply -f module.yml
# Metadata already updated, will retry upload

File Pattern Issues

Problem: Accidentally including large files or secrets

# Bad: Includes everything
contents:
  - "**/*"

Fix: Be specific and use ignoredContents:

# Good: Explicit inclusion
contents:
  - "src/**/*.py"
  - "requirements.txt"

ignoredContents:
  - "**/.env"           # Exclude secrets
  - "**/data/**"        # Exclude large datasets
  - "**/.git/**"        # Exclude version control

Best Practices

1. Use specific patterns

# Good: Explicit
contents:
  - "src/**/*.py"
  - "config/*.json"

# Avoid: Too broad
contents:
  - "**/*"

2. Always exclude sensitive files

ignoredContents:
  - "**/.env"
  - "**/.env.local"
  - "**/secrets/**"
  - "**/*.key"
  - "**/*.pem"

3. Exclude development artifacts

ignoredContents:
  - "**/__pycache__/**"
  - "**/*.pyc"
  - "**/.pytest_cache/**"
  - "**/node_modules/**"
  - "**/.venv/**"

4. Test patterns locally

# Verify what files will be included (dry run)
find . -path "./src/**/*.py" -o -name "requirements.txt"

5. Keep modules focused

One module per responsibility
Clear, descriptive names
Version your modules
Document dependencies

Version Control Integration

Recommended workflow:

# 1. Version module YAML alongside code
git/
└── my-module/
    ├── module.yml          # Module definition
    ├── src/
    │   └── *.py
    ├── requirements.txt
    └── README.md

# 2. Deploy from repository
cd my-module
kdx apply -f module.yml --profile prod

# 3. Tag releases
git tag -a v1.0.0 -m "Release v1.0.0"
git push --tags

Next Steps

Metadata Sync

Set up GitOps workflows for infrastructure as code

KDX CLI

Kodexa CLI (Legacy)

​Overview

​Discovering Resources

​List Available Resource Types

​Refresh Resource Discovery

​Reading Resources

​List Resources (GET Multiple)

​Get Specific Resource (GET Single)

​Describe Resource (Detailed View)

​Output Formats

​Table Output (Default)

​JSON Output

​YAML Output

​Creating Resources

​Create from File

​Create from JSON

​Create Multiple Resources

​Pre-Flight Validation

​Updating Resources

​Apply (Create or Update)

​Apply from Directory

​Dry Run (Preview Changes)

​Deleting Resources

​Delete by Name

​Force Delete (Skip Confirmation)

​Delete from File

​Production Environment Safety

​Production Confirmation Prompts

​Affected Operations

​Bypassing Confirmations (CI/CD)

​Read-Only Operations

​Resource Manifests

​Manifest Structure

​Example: Complete Workspace

​Example: Project with References

​Best Practices

​Use Declarative Configuration

​Apply Consistently

​Validate Before Committing

​Use Metadata for Organization

​Document Resource Dependencies

​Advanced Operations

​Filter Results (JSON)

​Bulk Operations

​Template-Based Creation

​Resource Comparison

​Validation Details

​Schema Validation

​Validation Error Examples

​Troubleshooting

​”Resource type not found”

​“Validation failed” errors

​“Resource not found” when it exists

​Changes not taking effect

​Module Deployment

​Overview

​Module YAML Structure

​Automatic Implementation Upload

​File Pattern Configuration

​Contents Patterns

​Ignored Patterns

​Complete Module Example

​Deploying a Module

​Module Workflow Examples

​New Module (First Deployment)

​Update Existing Module

​Module Without Implementation

​Production Workflow

​Troubleshooting

​No Files Found

​Upload Failed

​File Pattern Issues

​Best Practices

​Version Control Integration

​Next Steps

Metadata Sync

Overview

Discovering Resources

List Available Resource Types

Refresh Resource Discovery

Reading Resources

List Resources (GET Multiple)

Get Specific Resource (GET Single)

Describe Resource (Detailed View)

Output Formats

Table Output (Default)

JSON Output

YAML Output

Creating Resources

Create from File

Create from JSON

Create Multiple Resources

Pre-Flight Validation

Updating Resources

Apply (Create or Update)

Apply from Directory

Dry Run (Preview Changes)

Deleting Resources

Delete by Name

Force Delete (Skip Confirmation)

Delete from File

Production Environment Safety

Production Confirmation Prompts

Affected Operations

Bypassing Confirmations (CI/CD)

Read-Only Operations

Resource Manifests

Manifest Structure

Example: Complete Workspace

Example: Project with References

Best Practices

Use Declarative Configuration

Apply Consistently

Validate Before Committing

Use Metadata for Organization

Document Resource Dependencies

Advanced Operations

Filter Results (JSON)

Bulk Operations

Template-Based Creation

Resource Comparison

Validation Details

Schema Validation

Validation Error Examples

Troubleshooting

”Resource type not found”

“Validation failed” errors

“Resource not found” when it exists

Changes not taking effect

Module Deployment

Overview

Module YAML Structure

Automatic Implementation Upload

File Pattern Configuration

Contents Patterns

Ignored Patterns

Complete Module Example

Deploying a Module

Module Workflow Examples

New Module (First Deployment)

Update Existing Module

Module Without Implementation

Production Workflow

Troubleshooting

No Files Found

Upload Failed

File Pattern Issues

Best Practices

Version Control Integration

Next Steps