Documentation Index
Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Resource operations are the everyday CLI commands for platform metadata:
| Command | Purpose |
|---|
kdx api-resources | Discover resource types from the connected server |
kdx get | List resources or get one resource |
kdx describe | Render a detailed view of one resource |
kdx validate -f | Validate a resource YAML file against the live API schema |
kdx apply -f | Create or update a resource from YAML |
kdx delete | Delete one resource |
kdx run | Discover and call resource-specific API operations |
kdx create command. Use kdx apply -f <file> for create-or-update.
Discover Resources
kdx api-resources
kdx api-resources --refresh
kdx api-resources --schemes-only
--refresh after a platform upgrade or when a new resource type is missing from the local cache.
Current resource names you should use in new metadata include:
| Resource | Scope | Typical use |
|---|
activity-plan / activity-plans | Organization | Reusable Activity workflow definitions |
data-definition / data-definitions | Organization | Business data models and validation behavior |
data-form / data-forms | Organization | Task review forms |
task-template / task-templates | Organization | Human review work created by Activities |
task-status / task-statuses | Organization | Task status definitions bound into projects |
document-store / document-stores | Organization | Document storage and intake |
data-store / data-stores | Organization | Structured platform data stores |
module / modules | Organization | Processing modules |
service-bridge / service-bridges | Organization | External system integrations |
knowledge-set / knowledge-sets | Organization or project | Reusable knowledge collections |
project-template / project-templates | Organization | Reusable project scaffolds |
project / projects | Organization | Project workspace definitions |
intake / intakes | Organization | Upload and intake endpoints |
trigger / triggers | Project | Event bindings for Activity start behavior |
Read Resources
List resources:
kdx get projects
kdx get activity-plans
kdx get data-definitions
kdx get project invoice-processing
kdx get activity-plan invoice-intake
kdx describe data-definition invoice-data
kdx describe service-bridge finance-erp
kdx get projects -o json
kdx get activity-plans -o yaml
kdx get modules -o markdown
kdx get also supports --filter-name when you have presentation filters configured.
Interactive Tables
When kdx get <resource> runs in a terminal, it opens an interactive table when possible.
Common controls:
| Key | Action |
|---|
/ | Filter in the table |
Tab | Open the query panel |
r | Refresh |
Enter | Open row details |
PgUp / PgDn | Page through results |
Home / End | Move to first or last row |
-o json, -o yaml, or pipe output to disable table-oriented behavior for automation.
Filter And Sort Syntax
kdx get sends filters to the platform API. The current filter language is SpringFilter.
kdx get projects --filter "slug:'invoice-processing'"
kdx get document-families --filter "pendingProcessing:true"
kdx get activities --filter "status:'RUNNING'"
| Operator | Meaning | Example |
|---|
: | equals | slug:'invoice' |
! | not equals | status!'ARCHIVED' |
~ | like or contains | name~'*invoice*' |
> | greater than | createdOn>'2026-01-01' |
< | less than | updatedOn<'2026-05-01' |
and | both conditions | status:'ACTIVE' and slug~'*invoice*' |
or | either condition | status:'FAILED' or status:'PENDING' |
field:direction:
kdx get projects --sort "name:asc"
kdx get activities --sort "createdOn:desc;status:asc"
Validate YAML
Validate a resource file without sending changes:
kdx validate -f resources/activity-plans/invoice-intake.yaml
- The file parses as YAML.
- The file declares a
type.
- The type exists in the connected platform’s OpenAPI resource discovery.
- Required fields and known schema properties match the API schema where available.
Use validation before a PR or before a sync push:
find resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
Apply YAML
Apply creates or updates the resource described by a YAML file:
kdx apply -f resources/data-definitions/invoice-data.yaml
kdx apply -f resources/activity-plans/invoice-intake.yaml
kdx apply -f resources/modules/invoice-extractor/module.yml
type:
type: activity-plan
slug: invoice-intake
name: Invoice Intake
description: Extract, review, reconcile, and post invoice data
type: task-template
orgSlug: acme-finance
slug: invoice-review
name: Invoice Review
description: Human review task created by an Activity Plan
Module Apply
For type: module, kdx apply can upload both metadata and implementation content.
Current module metadata should use metadata.moduleRuntimeParameters:
type: module
orgSlug: acme-finance
slug: invoice-extractor
name: Invoice Extractor
metadata:
moduleRuntimeRef: kodexa/python
moduleRuntimeParameters:
module: invoice_extractor
implementation:
path: ./module
metadata.build:
metadata:
build:
- type: go
command: go build -o dist/processor ./cmd/processor
metadata.script or metadata.scriptPath. Inline-script-only modules do not need implementation upload.
type: module
orgSlug: acme-finance
slug: invoice-script-helpers
name: Invoice Script Helpers
metadata:
scriptLanguage: javascript
scriptPath: ../scripts/invoice-helpers.js
Delete Resources
kdx delete data-definition old-invoice-data
kdx delete activity-plan old-intake-plan
kdx delete project sandbox-project --force
Dynamic Operations
Use kdx run to list and call specialized API operations:
kdx run document-families
kdx run document-families data --id <document-family-id> --format json
kdx run activities get-activities --id <activity-id> -o json
Production Safety
Profiles can be marked as production:
kdx config set-profile prod \
--url https://platform.kodexa-enterprise.com \
--api-key <api-key> \
--production
--skip-production-confirm only when the pipeline has its own approval gate:
kdx apply -f resources/activity-plans/invoice-intake.yaml \
--profile prod \
--skip-production-confirm
When To Use Sync Instead
Use one-off resource operations for inspection, debugging, and small edits. Use kdx sync when:
- A project has multiple related resources.
- You need pull request review.
- You promote from dev to staging to production.
- Resources reference each other through project bindings.
- You need conflict detection and deterministic push ordering.
Troubleshooting
Resource Type Not Found
kdx api-resources --refresh
data-definition instead of older naming.
Apply Cannot Resolve A Resource
Check that the file includes type, slug, and any required orgSlug or projectSlug values:
kdx validate -f resource.yaml
Validation Fails On Unknown Fields
The connected server schema is authoritative. Refresh discovery and compare the YAML to the current API shape:
kdx api-resources --refresh
kdx validate -f resource.yaml
Changes Are Overwritten
For metadata repositories, run kdx sync pull before editing and commit .sync-state/ so conflict detection can protect against stale pushes.