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

# Native Files

> List and extract embedded native files such as PDFs, images, and Word documents from a KDDB document using kdx document natives commands.

Native files are binary documents (PDFs, images, Word files, etc.) embedded within a KDDB document. The `kdx document natives` commands let you list and extract these files.

## Commands

### List Native Files

View all native files embedded in a document:

```bash theme={null}
kdx document natives list <file.kddb>
```

**Example:**

```bash theme={null}
kdx document natives list invoice.kddb
```

```text theme={null}
┌────┬──────────────┬─────────────────┬────────┐
│ ID │   FILENAME   │    MIMETYPE     │  SIZE  │
├────┼──────────────┼─────────────────┼────────┤
│ 1  │ original.pdf │ application/pdf │ 245632 │
│ 2  │ signature.png│ image/png       │  12480 │
└────┴──────────────┴─────────────────┴────────┘
```

If no native files are found:

```text theme={null}
No native files found in document
```

### Extract Native Files

Extract a native file to disk:

```bash theme={null}
kdx document natives extract <file.kddb> <filename-or-id> [flags]
```

**Flags:**

| Flag           | Description                                   |
| -------------- | --------------------------------------------- |
| `-o, --output` | Output file path (default: original filename) |

**Examples:**

```bash theme={null}
# Extract by filename
kdx document natives extract invoice.kddb original.pdf

# Extract by ID
kdx document natives extract invoice.kddb 1

# Extract to a specific path
kdx document natives extract invoice.kddb original.pdf -o /tmp/extracted.pdf
```

**Output:**

```text theme={null}
Extracted original.pdf (245632 bytes) to original.pdf
```

## Output Formats

Use the global `-o` flag for different output formats:

```bash theme={null}
# JSON output for scripting
kdx document natives list invoice.kddb -o json

# YAML output
kdx document natives list invoice.kddb -o yaml
```

**JSON output example:**

```json theme={null}
[
  {
    "id": 1,
    "filename": "original.pdf",
    "mimeType": "application/pdf",
    "size": 245632
  },
  {
    "id": 2,
    "filename": "signature.png",
    "mimeType": "image/png",
    "size": 12480
  }
]
```

## Use Cases

### Extract All Files

Extract all native files from a document:

```bash theme={null}
# List files and extract each one
for file in $(kdx document natives list invoice.kddb -o json | jq -r '.[].filename'); do
  kdx document natives extract invoice.kddb "$file"
done
```

### Verify Original Document

Check if the original source file is preserved:

```bash theme={null}
# Check for PDF
kdx document natives list processed.kddb | grep -i pdf
```

### Batch Processing

Extract specific file types across multiple documents:

```bash theme={null}
# Extract all PDFs from all KDDB files
for kddb in *.kddb; do
  echo "Processing $kddb..."
  kdx document natives list "$kddb" -o json | jq -r '.[] | select(.mimeType == "application/pdf") | .filename' | while read filename; do
    kdx document natives extract "$kddb" "$filename" -o "extracted/${kddb%.kddb}_$filename"
  done
done
```

## Common MIME Types

| File Type    | MIME Type                                                                 |
| ------------ | ------------------------------------------------------------------------- |
| PDF          | `application/pdf`                                                         |
| Word (docx)  | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| Excel (xlsx) | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
| PNG          | `image/png`                                                               |
| JPEG         | `image/jpeg`                                                              |
| TIFF         | `image/tiff`                                                              |
| Plain Text   | `text/plain`                                                              |

## Notes

<Note>
  Native files are stored compressed (gzip) within the KDDB file. The `extract` command automatically decompresses the data when writing to disk.
</Note>

<Warning>
  Not all KDDB documents contain native files. Documents created from text input or API responses may not have embedded originals.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="SDK: Native Documents" icon="code" href="/sdk/native-documents">
    Work with native documents programmatically
  </Card>

  <Card title="Document Overview" icon="file-lines" href="/guides/kdx-cli/document/overview">
    Back to document commands overview
  </Card>
</CardGroup>