> ## 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.

# Resource Operations

> Use KDX CLI resource operations to discover, read, validate, apply, delete, and execute Kodexa Platform resources from the terminal.

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

```bash theme={null}
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:

```bash theme={null}
kdx get projects
kdx get activity-plans
kdx get data-definitions
```

Get one resource:

```bash theme={null}
kdx get project invoice-processing
kdx get activity-plan invoice-intake
```

Render a schema-aware detailed view:

```bash theme={null}
kdx describe data-definition invoice-data
kdx describe service-bridge finance-erp
```

Use output formats for scripting:

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
kdx get projects --sort "name:asc"
kdx get activities --sort "createdOn:desc;status:asc"
```

## Validate YAML

Validate a resource file without sending changes:

```bash theme={null}
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`:

```bash theme={null}
find resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
```

## Apply YAML

Apply creates or updates the resource described by a YAML file:

```bash theme={null}
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`:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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`:

```yaml theme={null}
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`:

```yaml theme={null}
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.

```yaml theme={null}
type: module
orgSlug: acme-finance
slug: invoice-script-helpers
name: Invoice Script Helpers
metadata:
  scriptLanguage: javascript
  scriptPath: ../scripts/invoice-helpers.js
```

## Delete Resources

```bash theme={null}
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:

```bash theme={null}
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](/guides/kdx-cli/dynamic-api).

## Production Safety

Profiles can be marked as production:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.