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

# Command Reference

> Complete reference for kdx CLI commands, global flags, authentication, profiles, sync, document, knowledge, and secret operations on the Kodexa Platform.

# Command Reference

This page covers the current KDX command surface. It focuses on Activity-centered resource work, GitOps metadata promotion, document operations, knowledge attachments, and secure operational setup.

## Global Flags

Global flags can be used with most commands.

| Flag                                           | Description                                              |
| ---------------------------------------------- | -------------------------------------------------------- |
| `-o, --output table\|json\|yaml\|markdown`     | Output format for commands that support formatted output |
| `--profile <name>`                             | Use a named profile instead of the current profile       |
| `--url <url>`                                  | Override the profile URL                                 |
| `--api-key <key>`                              | Override the profile API key                             |
| `--debug`                                      | Enable debug logging                                     |
| `--log-level debug\|info\|warn\|error\|silent` | Set log level                                            |
| `--log-timestamps`                             | Include timestamps in logs                               |
| `--skip-production-confirm`                    | Skip production confirmation prompts and log the bypass  |
| `--strict`                                     | Treat validation warnings as errors where supported      |

## Authentication and Profiles

| Command                                                     | Purpose                                          |
| ----------------------------------------------------------- | ------------------------------------------------ |
| `kdx login <url>`                                           | Authenticate in a browser and save an API key    |
| `kdx login <url> --device`                                  | Use device-code login for headless environments  |
| `kdx login <url> --no-browser`                              | Print the login URL instead of opening a browser |
| `kdx config set-profile <name> --url <url> --api-key <key>` | Create or update a profile                       |
| `kdx config use-profile <name>`                             | Switch the current profile                       |
| `kdx config list-profiles`                                  | List configured profiles                         |
| `kdx config current-profile`                                | Show the current profile                         |
| `kdx config delete-profile <name>`                          | Delete a profile                                 |

Use profiles for local and interactive work. Use `sync-config.yaml` environment entries for GitOps deployment jobs.

## Discovery

### `kdx api-resources`

Lists resource types discovered from the platform OpenAPI contract.

```bash theme={null}
kdx api-resources
kdx api-resources --refresh
kdx api-resources --schemes-only
```

| Flag             | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `--refresh`      | Refresh the local OpenAPI/resource cache             |
| `--schemes-only` | Show raw resource schemes without operation metadata |

Use `--refresh` after a platform upgrade or when docs mention a resource type your local CLI cache does not know yet.

## Resource Inspection

### `kdx get`

Displays one or many resources.

```bash theme={null}
kdx get <resource-type>
kdx get <resource-type> <id-or-slug>
```

Examples:

```bash theme={null}
kdx get activity-plans
kdx get data-definitions -o json
kdx get projects --filter-name active
kdx get module invoice-module --download --download-path ./invoice-module.zip
```

| Flag                     | Description                                       |
| ------------------------ | ------------------------------------------------- |
| `--filter-name <name>`   | Apply a named filter from CLI presentation config |
| `--download`             | Download a module implementation ZIP              |
| `--download-path <path>` | Output path for a module implementation download  |

### `kdx describe`

Shows schema-aware detail for one resource.

```bash theme={null}
kdx describe <resource-type> <id-or-slug>
```

Examples:

```bash theme={null}
kdx describe activity-plan invoice-intake
kdx describe data-definition invoice-data
```

## Resource Authoring

### `kdx validate`

Validates a YAML resource file against the OpenAPI schema without sending it to the server.

```bash theme={null}
kdx validate -f resources/activity-plans/invoice-intake.yaml
```

| Flag                    | Description                    |
| ----------------------- | ------------------------------ |
| `-f, --filename <path>` | Resource YAML file to validate |

### `kdx apply`

Creates or updates a resource from YAML.

```bash theme={null}
kdx apply -f resources/activity-plans/invoice-intake.yaml
```

| Flag                    | Description                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `-f, --filename <path>` | Resource YAML file to apply                                                                                                   |
| `--type <type>`         | Resource type (e.g. `knowledge-set`); overrides the file's `type`. Useful for files pulled via `kdx sync`, which are untyped. |
| `--org-slug <slug>`     | Organization slug used to resolve and create the resource; overrides the file's `orgSlug`.                                    |

There is no general `kdx create` command. Use `kdx apply -f <file>` for declarative create-or-update.

### `kdx delete`

Deletes a resource using the delete operation discovered for that resource type.

```bash theme={null}
kdx delete <resource-type> <id-or-slug> [--force]
```

Examples:

```bash theme={null}
kdx delete data-form invoice-review-form
kdx delete activity-plan invoice-intake --force
```

## Dynamic API Operations

### `kdx run`

Lists and executes resource-specific operations discovered from OpenAPI. Use it when an operation exists in the API but does not have a dedicated high-level CLI command.

```bash theme={null}
kdx run <resource-type>
kdx run <resource-type> <operation> --param value --body '{"key":"value"}'
```

Examples:

```bash theme={null}
kdx run activity-plans
kdx run document-families assess --id a700ca3e-38e7-4e63-8974-59c2e9058cf3
```

## Metadata Sync

### `kdx sync pull`

Downloads metadata resources from an environment into a metadata repository.

```bash theme={null}
kdx sync pull --target ap-team --env dev
```

Common flags:

| Flag                    | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `--target <name>`       | Target name from `sync-config.yaml`; repeatable      |
| `--env <name>`          | Source environment name from `sync-config.yaml`      |
| `--from-profile <name>` | Source profile override                              |
| `--from-url <url>`      | Source URL override                                  |
| `--from-api-key <key>`  | Source API key override                              |
| `--skip-missing`        | Skip resources not found on the server               |
| `--discover`            | Discover resources and generate or update a manifest |
| `--discover-dir <dir>`  | Set manifest `metadata_dir` during discovery         |
| `-f, --filter <regex>`  | Filter resources by slug or project slug             |
| `--threads <n>`         | Parallel pull workers                                |

### `kdx sync push`

Uploads local metadata files to a Kodexa environment.

```bash theme={null}
kdx sync push --target ap-team --env dev --dry-run
kdx sync push --target ap-team --env dev
```

Common flags:

| Flag                   | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--target <name>`      | Target name from `sync-config.yaml`; repeatable |
| `--env <name>`         | Destination environment name                    |
| `--to-profile <name>`  | Destination profile override                    |
| `--to-url <url>`       | Destination URL override                        |
| `--to-api-key <key>`   | Destination API key override                    |
| `--dry-run`            | Preview actions without changing the server     |
| `-f, --filter <regex>` | Filter resources by slug                        |
| `--force`              | Overwrite conflict-detected resources           |
| `--threads <n>`        | Parallel push workers                           |

### `kdx sync deploy`

Deploys targets based on branch mappings, tag mappings, or explicit flags.

```bash theme={null}
kdx sync deploy --branch main --dry-run
kdx sync deploy --target ap-team --env prod --confirm-all
```

Common flags:

| Flag                   | Description                               |
| ---------------------- | ----------------------------------------- |
| `--target <name>`      | Target name to deploy; repeatable         |
| `--env <name>`         | Environment to deploy to                  |
| `--branch <name>`      | Branch name to use for branch mapping     |
| `--tag <name>`         | Tag name to use for tag mapping           |
| `--dry-run`            | Preview deployment                        |
| `--force`              | Push despite sync conflicts               |
| `--confirm-each`       | Confirm each target before deployment     |
| `--confirm-all`        | Confirm once before deploying all targets |
| `-f, --filter <regex>` | Filter resources by slug                  |
| `--output-json <path>` | Write deployment report JSON              |
| `--threads <n>`        | Parallel deployment workers               |

The sync command also supports global sync flags `--metadata-dir <path>` and `--config <path>`.

## Project Templates

### `kdx project create`

Creates a project from a project template.

```bash theme={null}
kdx project create \
  --template acme/ap-intake \
  --org acme \
  --name "AP Pilot" \
  --description "Pilot for invoice intake"
```

| Flag                        | Description                  |
| --------------------------- | ---------------------------- |
| `--template <org/template>` | Project template reference   |
| `--org <org-slug>`          | Destination organization     |
| `--name <name>`             | New project name             |
| `--description <text>`      | Optional project description |

## Document Store Operations

| Command                                | Purpose                     |
| -------------------------------------- | --------------------------- |
| `kdx store upload <store-ref> <file>`  | Upload a source document    |
| `kdx store watch <document-family-id>` | Wait for a processing label |
| `kdx store stats <store-name>`         | Show store statistics       |
| `kdx store reindex <store-name>`       | Trigger store reindexing    |

See [Store Commands](/guides/kdx-cli/store-commands) for details.

## Document Family Operations

| Command                                                  | Purpose                        |
| -------------------------------------------------------- | ------------------------------ |
| `kdx document-family data <id>`                          | Export extracted JSON          |
| `kdx document-family content list <id>`                  | List content objects           |
| `kdx document-family content download <id> [content-id]` | Download a KDDB content object |
| `kdx document-family add-label <id> <tag-id>`            | Add a label                    |
| `kdx document-family remove-label <id> <label-id>`       | Remove a label                 |
| `kdx document-family set-status <id> <status-id>`        | Set status                     |

See [Document Family Commands](/guides/kdx-cli/document-family-commands) for details.

## Knowledge Attachments

| Command                                           | Purpose                 |
| ------------------------------------------------- | ----------------------- |
| `kdx knowledge attach <item-ref> --file <path>`   | Attach one file         |
| `kdx knowledge attach <item-ref> --folder <path>` | Zip and attach a folder |
| `kdx knowledge download <item-ref>`               | Download the attachment |

See [Knowledge Commands](/guides/kdx-cli/knowledge-commands) for details.

## Organization Secrets

| Command                                             | Purpose                          |
| --------------------------------------------------- | -------------------------------- |
| `kdx secret list <org-slug>`                        | List secret names                |
| `kdx secret set <org-slug> <name>`                  | Set a secret interactively       |
| `kdx secret set <org-slug> <name> --from-env <env>` | Set from an environment variable |
| `kdx secret delete <org-slug> <name>`               | Delete a secret                  |

See [Secret Commands](/guides/kdx-cli/secret-commands) for details.

## Local Document Commands

The `kdx document` command works with local `.kddb` files. It is the main CLI surface for local document inspection and debugging.

| Area      | Commands                                                                                           |
| --------- | -------------------------------------------------------------------------------------------------- |
| Reading   | `info`, `stats`, `text`, `page`, `grep`, `lines`                                                   |
| Search    | `query`, `find`, `locate`, `spatial find`, `spatial bbox`                                          |
| Structure | `print`, `node`, `tags`, `features`                                                                |
| Data      | `data objects`, `data attributes`, `data exceptions`, `data create`, `data set-attribute`          |
| Metadata  | `metadata get`, `metadata set`, `external list`, `external get`, `external set`, `external delete` |
| Files     | `native list`, `native extract`                                                                    |
| Audit     | `audit`, `delta`                                                                                   |

See the [Document Commands overview](/guides/kdx-cli/document/overview) for the full local document command set.

## Version

```bash theme={null}
kdx version
```

Prints the CLI version, Git commit, and build date.