Resource Operations - Kodexa Developer Portal

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

There is no general 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

Use --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

Compatibility aliases may still resolve for older names, but new examples and new files should use the current names above.

Read Resources

List resources:

kdx get projects
kdx get activity-plans
kdx get data-definitions

Get one resource:

kdx get project invoice-processing
kdx get activity-plan invoice-intake

Render a schema-aware detailed view:

kdx describe data-definition invoice-data
kdx describe service-bridge finance-erp

Use output formats for scripting:

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

Use -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'"

Common operators:

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'`

Sort syntax uses 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

Validation checks:

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

A minimal current-shape resource starts with a type:

type: activity-plan
slug: invoice-intake
name: Invoice Intake
description: Extract, review, reconcile, and post invoice data

For project-scoped or project-bound resources, include organization and project context when required by the server schema:

type: task-template
orgSlug: acme-finance
slug: invoice-review
name: Invoice Review
description: Human review task created by an Activity Plan

Supplying `type` and `org` with flags

If a file omits type (or, for slug-based resources, orgSlug), pass them on the command line instead of editing the file. This is the common case for files produced by kdx sync pull, which are intentionally untyped and organization-agnostic:

kdx apply -f resources/knowledge-sets/invoice-terms.yaml \
  --type knowledge-set \
  --org-slug acme-finance

--type takes the same value you would put in a type: field (for example knowledge-set). It overrides the file’s type when both are present.
--org-slug supplies the organization used to resolve the resource (scheme://org-slug/slug) and, when creating a new resource, to set its owning organization. It overrides the file’s orgSlug.

When a flag is omitted, the value from the file is used, so existing self-describing files are unaffected.

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

If a module needs a build step before packaging, declare metadata.build:

metadata:
  build:
    - type: go
      command: go build -o dist/processor ./cmd/processor

If a module is an inline JavaScript helper, use 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

Delete operations are server-defined. The CLI uses the discovered delete operation for the resource type and asks for production confirmation when the active profile is marked production.

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

See Dynamic API Operations.

Production Safety

Profiles can be marked as production:

kdx config set-profile prod \
  --url https://platform.kodexa-enterprise.com \
  --api-key <api-key> \
  --production

Mutating commands prompt before changing production resources. For CI/CD, use --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

Then use the current resource name, such as 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

If the file legitimately omits type or orgSlug — for example a file pulled via kdx sync — supply them with flags instead of editing the file:

kdx apply -f resource.yaml --type knowledge-set --org-slug acme-finance

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.

​Overview

​Discover Resources

​Read Resources

​Interactive Tables

​Filter And Sort Syntax

​Validate YAML

​Apply YAML

​Supplying type and org with flags

​Module Apply

​Delete Resources

​Dynamic Operations

​Production Safety

​When To Use Sync Instead

​Troubleshooting

​Resource Type Not Found

​Apply Cannot Resolve A Resource

​Validation Fails On Unknown Fields

​Changes Are Overwritten