> ## 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. # CLI Use Cases > Understand where the kdx CLI fits across Kodexa development, GitOps deployment, Activity Plan promotion, document operations, and day-to-day debugging tasks. # 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: ```bash theme={null} 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: ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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. ```bash theme={null} # 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: ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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 ` | | Understand one resource | `kdx describe ` | | Create or update one YAML resource | `kdx apply -f ` | | Validate one YAML resource | `kdx validate -f ` | | 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 ...` |