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

# External Data with kdx CLI

> Manage key-value external data stored in KDDB documents from the kdx CLI for custom data, processing results, or extension-specific information.

External data provides a flexible key-value store within KDDB documents for storing custom data, processing results, or extension-specific information.

## Commands

### List Keys

View all external data keys in a document:

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

**Example:**

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

```text theme={null}
┌─────────────────┐
│       KEY       │
├─────────────────┤
│ ocr_results     │
│ extraction_config│
│ processing_status│
└─────────────────┘
```

If no external data exists:

```text theme={null}
No external data keys found
```

### Get Value

Retrieve the value for a specific key:

```bash theme={null}
kdx document external get <file.kddb> <key>
```

**Example:**

```bash theme={null}
kdx document external get invoice.kddb processing_status
```

```text theme={null}
┌───────────────┬─────────────────────────────────────┐
│     FIELD     │                VALUE                │
├───────────────┼─────────────────────────────────────┤
│ status        │ completed                           │
│ processed_at  │ 2024-01-15T10:30:00Z                │
│ pages_processed│ 5                                  │
└───────────────┴─────────────────────────────────────┘
```

### Set Value

Store or update a value for a key:

```bash theme={null}
kdx document external set <file.kddb> <key> <json-value>
```

<Warning>
  The value must be valid JSON. Strings must be quoted, objects use curly braces, etc.
</Warning>

**Examples:**

```bash theme={null}
# Set a string value
kdx document external set invoice.kddb status '"processed"'

# Set a number
kdx document external set invoice.kddb confidence '0.95'

# Set a boolean
kdx document external set invoice.kddb reviewed 'true'

# Set an object
kdx document external set invoice.kddb processing_status '{"status": "completed", "pages": 5}'

# Set an array
kdx document external set invoice.kddb tags '["invoice", "urgent", "reviewed"]'
```

**Output:**

```text theme={null}
Set external data key: processing_status
```

### Delete Key

Remove an external data key:

```bash theme={null}
kdx document external delete <file.kddb> <key>
```

**Example:**

```bash theme={null}
kdx document external delete invoice.kddb temp_data
```

```text theme={null}
Deleted external data key: temp_data
```

## Output Formats

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

```bash theme={null}
# JSON output
kdx document external get invoice.kddb processing_status -o json

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

**JSON output example:**

```json theme={null}
{
  "status": "completed",
  "processed_at": "2024-01-15T10:30:00Z",
  "pages_processed": 5
}
```

## JSON Value Examples

Since values must be valid JSON, here are common patterns:

| Value Type | JSON Syntax       | Example              |
| ---------- | ----------------- | -------------------- |
| String     | `"value"`         | `'"hello world"'`    |
| Number     | `123` or `3.14`   | `'42'`               |
| Boolean    | `true` or `false` | `'true'`             |
| Null       | `null`            | `'null'`             |
| Array      | `[...]`           | `'["a", "b", "c"]'`  |
| Object     | `{...}`           | `'{"key": "value"}'` |

<Tip>
  Use single quotes around the JSON value in bash to prevent shell expansion of special characters.
</Tip>

## Use Cases

### Store Processing Results

Save extraction or analysis results:

```bash theme={null}
# Store OCR confidence
kdx document external set invoice.kddb ocr_confidence '0.92'

# Store extraction results
kdx document external set invoice.kddb extraction '{"vendor": "Acme Corp", "total": 1234.56}'
```

### Track Processing Status

Maintain workflow state:

```bash theme={null}
# Mark as processed
kdx document external set invoice.kddb status '"completed"'

# Store processing metadata
kdx document external set invoice.kddb processing '{"model": "invoice-v2", "timestamp": "2024-01-15T10:30:00Z"}'
```

### Configuration Storage

Store document-specific configuration:

```bash theme={null}
# Store extraction config
kdx document external set invoice.kddb config '{"extract_tables": true, "language": "en"}'
```

### Scripting Integration

Use external data in automated workflows:

```bash theme={null}
# Check if document was processed
STATUS=$(kdx document external get invoice.kddb status -o json 2>/dev/null)
if [ "$STATUS" = '"completed"' ]; then
  echo "Already processed"
else
  echo "Needs processing"
fi

# Copy external data between documents
VALUE=$(kdx document external get source.kddb config -o json)
kdx document external set target.kddb config "$VALUE"
```

## Notes

<Note>
  External data is stored as JSON in the KDDB database. Complex nested structures are fully supported.
</Note>

<Warning>
  Modifying external data changes the KDDB file. Make backups before making changes to important documents.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="SDK: External Data" icon="code" href="/sdk/external-data">
    Work with external data programmatically
  </Card>

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