CLI Use Cases

The KDX CLI is not just a wrapper around API calls. It gives platform builders a repeatable way to inspect, promote, test, and operate Kodexa resources without having to click through the UI. Use the CLI when you need a fast feedback loop, a scriptable workflow, or an auditable path from Git to a Kodexa environment.

The Mental Model

Area	What the CLI does	Typical commands
Resource inspection	Lists and describes platform resources discovered from OpenAPI	`get`, `describe`, `api-resources`
Resource authoring	Validates and applies YAML definitions	`validate`, `apply`, `delete`
GitOps	Pulls, pushes, and deploys metadata repositories	`sync pull`, `sync push`, `sync deploy`
Activity development	Moves Activity Plans, task templates, data forms, service bridges, and supporting resources through environments	`sync`, `apply`, `validate`, `project create`
Document operations	Uploads documents, waits for processing, exports data, and downloads KDDB content	`store`, `document-family`, `document`
Knowledge operations	Attaches and downloads files or folders for knowledge items	`knowledge attach`, `knowledge download`
Secure setup	Manages organization secrets without putting values in shell history	`secret list`, `secret set`, `secret delete`

Build an Activity Plan Locally

When you are designing an Activity Plan, the CLI helps you keep the resource set together:

kdx validate -f resources/activity-plans/invoice-intake.yaml
kdx validate -f resources/task-templates/invoice-review.yaml
kdx apply -f resources/activity-plans/invoice-intake.yaml
kdx apply -f resources/task-templates/invoice-review.yaml

For a larger build, use sync manifests so the whole Activity-centered resource set moves together:

kdx sync push --target ap-team --env dev --dry-run
kdx sync push --target ap-team --env dev

Promote a Project Template

Project templates remain useful because they package repeatable project setup. With Activity Plans, a template should bind the project to current plans, task templates, data forms, labels, statuses, service bridges, and document stores.

kdx project create \
  --template acme/ap-intake \
  --org acme \
  --name "AP Pilot"

After creating the project, use kdx get projects, kdx get activity-plans, and kdx get task-templates to confirm that the expected resources exist and are bound.

Test a Document Processing Path

A common development loop is upload, wait, export:

kdx store upload acme/ap-processing ./fixtures/invoice.pdf
kdx store watch a700ca3e-38e7-4e63-8974-59c2e9058cf3 --timeout 900
kdx document-family data a700ca3e-38e7-4e63-8974-59c2e9058cf3 -o output/invoice.json

When the export is surprising, download the KDDB file and inspect it locally:

kdx document-family content download a700ca3e-38e7-4e63-8974-59c2e9058cf3 --latest -o invoice.kddb
kdx document text invoice.kddb --pages 1:3
kdx document find invoice.kddb --contains "Invoice Number" --type line

Manage a Metadata Repository

Use kdx sync when resources should live in Git and be promoted through environments.

# Pull current state into the repository
kdx sync pull --target ap-team --env dev

# Review and edit YAML in Git
git diff

# Preview the push
kdx sync push --target ap-team --env dev --dry-run

# Push the changes
kdx sync push --target ap-team --env dev

For CI, let branch and tag mappings decide what deploys:

kdx sync deploy --branch main --dry-run --output-json deploy-report.json
kdx sync deploy --branch main --confirm-all

Inspect the Platform Contract

The CLI discovers resource types from the platform OpenAPI contract. Refresh the local cache after a platform upgrade or when a new resource type is added.

kdx api-resources --refresh
kdx api-resources
kdx run activity-plans

Use kdx run when you need an operation that exists in the API but does not have a dedicated high-level command yet.

Secure Runtime Configuration

Use organization secrets for values that Activity steps and service bridges need at runtime.

kdx secret list acme
kdx secret set acme ERP_API_TOKEN --from-env ERP_API_TOKEN
kdx secret delete acme OLD_ERP_API_TOKEN

Secret values are write-only through the CLI. The list command returns names, not values.

Attach Knowledge Assets

Knowledge items can carry supporting assets such as examples, reference files, evaluation data, or images used in Markdown content.

kdx knowledge attach invoice-rules --file ./examples/invoice-rules.md
kdx knowledge attach invoice-rules --folder ./examples --id invoice-examples
kdx knowledge download invoice-rules -o invoice-rules.zip

When you pass --id, the CLI prints the attachment reference that can be used from Markdown content.

Choose the Right Command

You need to…	Start with
See what resources exist	`kdx get <resource-type>`
Understand one resource	`kdx describe <resource-type> <id-or-slug>`
Create or update one YAML resource	`kdx apply -f <file>`
Validate one YAML resource	`kdx validate -f <file>`
Move many resources between environments	`kdx sync pull`, `kdx sync push`, `kdx sync deploy`
Create a project from a template	`kdx project create`
Upload and monitor documents	`kdx store upload`, `kdx store watch`
Export processed data	`kdx document-family data`
Debug local KDDB files	`kdx document ...`
Manage secrets	`kdx secret ...`
Attach knowledge assets	`kdx knowledge ...`

Getting Started

Core Operations

Sync & GitOps

Operational Commands

Document Commands

CLI Use Cases

CLI Use Cases

The Mental Model

Build an Activity Plan Locally

Promote a Project Template

Test a Document Processing Path

Manage a Metadata Repository

Inspect the Platform Contract

Secure Runtime Configuration

Attach Knowledge Assets

Choose the Right Command

​CLI Use Cases

​The Mental Model

​Build an Activity Plan Locally

​Promote a Project Template

​Test a Document Processing Path

​Manage a Metadata Repository

​Inspect the Platform Contract

​Secure Runtime Configuration

​Attach Knowledge Assets

​Choose the Right Command

CLI Use Cases

The Mental Model

Build an Activity Plan Locally

Promote a Project Template

Test a Document Processing Path

Manage a Metadata Repository

Inspect the Platform Contract

Secure Runtime Configuration

Attach Knowledge Assets

Choose the Right Command