Skip to main content

​
Overview

kdx run exposes resource-specific API operations discovered from the platform OpenAPI specification. Use it when you need an operation that is not covered by a stable top-level command. 
kdx run <resource-type> [operation] [flags]
Examples of good kdx run use cases:
  • Inspect operations available for activities, activity-plans, document-families, or projects.
  • Call a document-family export, external-data, label, touch, or status endpoint.
  • Run administrative project operations exposed by the current platform.
  • Prototype an integration before turning it into application code.

​
How Discovery Works

List available operations for a resource: 
kdx run document-families
kdx run activities
kdx run projects
The operation list comes from the connected environment. If an operation is missing after a platform upgrade, refresh the discovery cache: 
kdx api-resources --refresh

​
Executing An Operation

Path and query parameters are passed as dynamic flags. Request bodies are passed as JSON with --body. 
kdx run <resource-type> <operation> --id <id> --body '{"key":"value"}'
Parameter handling:
Parameter typeHow to pass it
Path parameter--id <value>, --ref <value>, or the parameter name shown by kdx run <resource>
Query parameter--format json, --includeIds true, --filter "slug:'invoice'"
Request body--body '{"statusId":"..."}'
Output format-o json, -o yaml, -o table

​
Common Operations

​
Document Families

# List available document-family operations
kdx run document-families

# Get document-family details
kdx run document-families get-document-families --id <document-family-id>

# Get extracted data
kdx run document-families data --id <document-family-id> --format json

# List external data keys
kdx run document-families external-data-keys --id <document-family-id>

# Get one external data value
kdx run document-families external-data-get --id <document-family-id> --key transformed_objects

# Get processing steps for operational review
kdx run document-families steps --id <document-family-id>

# Touch a document family to emit a platform event
kdx run document-families touch --id <document-family-id>
For routine data export, prefer the stable wrapper: 
kdx document-family data <document-family-id> -o extracted.json

​
Activities

# Discover Activity operations exposed by this environment
kdx run activities

# Get an Activity run; current Activity APIs include materialized step data
kdx run activities get-activities --id <activity-id> -o json
Use activities when you need to inspect the business process run itself. Use activity-plans when you need to inspect the reusable workflow definition.

​
Projects

# Discover project-specific operations
kdx run projects

# Get project resources or project-specific forms when exposed by the API
kdx run projects get-apiprojects-resources --id <project-id>
kdx run projects get-apiprojects-dataforms --id <project-id>
For creating a project from a template, prefer: 
kdx project create --template <org/template> --org <org-slug> --name <project-name>

​
Data Definitions

Use the current data-definitions resource name for new work: 
kdx run data-definitions
kdx get data-definitions
kdx describe data-definition invoice-data
Some servers still expose compatibility aliases for older names. New documentation and new metadata should use data-definition and data-definitions.

​
Service Bridges

kdx run service-bridges
kdx get service-bridges
For Activity workflow calls, prefer defining a BRIDGE_CALL step in an Activity Plan. Use kdx run for inspection, troubleshooting, and one-off administrative calls exposed by the API.

​
Output And Scripting

# Get Activity status for scripting
kdx run activities get-activities --id "$ACTIVITY_ID" -o json | jq '.status'

# Export external data for another tool
kdx run document-families external-data-get \
  --id "$DOCUMENT_FAMILY_ID" \
  --key transformed_objects \
  -o json > transformed-objects.json

​
When To Use run

Use kdx run when:
  • You need an API operation that is not modeled as a top-level CLI command.
  • You want to inspect what the current server supports.
  • You are building an automation and want to verify the API call shape.
Use a stable command when it exists:
NeedPrefer
List or inspect resourceskdx get, kdx describe
Create or update YAML resourceskdx apply -f
Validate YAMLkdx validate -f
Export document-family datakdx document-family data
Download KDDB contentkdx document-family content download
Version metadatakdx sync

​
Troubleshooting

​
Operation Not Found

List the operations exposed by the current environment: 
kdx run <resource-type>
Then refresh discovery if needed: 
kdx api-resources --refresh

​
Missing Required Parameter

The operation list shows required path and body parameters. Add the corresponding dynamic flag: 
kdx run document-families get-document-families --id <document-family-id>

​
Invalid JSON Body

Validate the body with jq before passing it: 
echo '{"statusId":"..."}' | jq .
kdx run document-families status --id <document-family-id> --body '{"statusId":"..."}'

​
Resource Name Drift

Use current resource names in new commands and docs:
Current nameNotes
data-definitionsCurrent name for business data models
activity-plansReusable workflow definitions
activitiesRunning workflow instances
task-templatesHuman work templates used by Activity CREATE_TASK steps