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

# Knowledge Commands

> Use kdx knowledge attach and download commands to upload files, zipped folders, and supporting assets to Kodexa knowledge items, then retrieve them later.

# Knowledge Commands

The `kdx knowledge` command manages attachments on knowledge items. Attachments are useful when a knowledge item needs supporting files such as example documents, reference datasets, prompt examples, diagrams, Markdown assets, or evaluation material.

## Available Commands

| Command    | Description                                        |
| ---------- | -------------------------------------------------- |
| `attach`   | Upload a file or zipped folder to a knowledge item |
| `download` | Download the attachment from a knowledge item      |

## Attach a File

```bash theme={null}
kdx knowledge attach <knowledge-item-ref> --file <path> [--id <attachment-id>]
```

The knowledge item reference can be a UUID or slug.

Examples:

```bash theme={null}
kdx knowledge attach invoice-rules --file ./rules.md
kdx knowledge attach invoice-rules --file ./logo.png --id invoice-logo
```

When `--id` is omitted, the CLI creates an attachment ID from the filename. When `--id` is supplied, the output includes the Markdown attachment reference.

```text theme={null}
Uploading attachment to knowledge item 'invoice-rules'...
Attached: logo.png (hash: sha256:...)
Markdown reference: ![](attachment://invoice-logo)
```

## Attach a Folder

```bash theme={null}
kdx knowledge attach <knowledge-item-ref> --folder <path> [--id <attachment-id>]
```

The CLI zips the folder contents before upload.

Example:

```bash theme={null}
kdx knowledge attach invoice-rules --folder ./examples --id invoice-examples
```

Use folder attachments when the knowledge item needs a collection of files that should move together.

## Download an Attachment

```bash theme={null}
kdx knowledge download <knowledge-item-ref> [-o <path>]
```

Examples:

```bash theme={null}
# Download using the original attachment filename
kdx knowledge download invoice-rules

# Download to a specific location
kdx knowledge download invoice-rules -o ./downloads/invoice-rules.zip
```

If no output path is supplied, the CLI asks the platform for attachment metadata and uses the original filename when available.

## Use Cases

| Use case                         | Command                                                                    |
| -------------------------------- | -------------------------------------------------------------------------- |
| Attach a Markdown reference file | `kdx knowledge attach item-slug --file ./reference.md`                     |
| Attach examples as one bundle    | `kdx knowledge attach item-slug --folder ./examples --id examples`         |
| Pull a bundle for local review   | `kdx knowledge download item-slug -o examples.zip`                         |
| Update an image used in Markdown | `kdx knowledge attach item-slug --file ./diagram.png --id process-diagram` |

## Troubleshooting

| Symptom                                           | What to check                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------- |
| `either --file or --folder must be specified`     | Pass one attachment source.                                         |
| `only one of --file or --folder can be specified` | Upload either a single file or a folder bundle, not both.           |
| Folder upload fails because it is empty           | Confirm the folder contains files; empty folders are not uploaded.  |
| Markdown image does not render                    | Confirm the attachment ID matches the `attachment://...` reference. |