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

# Document Metadata with kdx CLI

> View and modify document metadata in KDDB files from the kdx CLI, including UUID, version, source information, labels, and custom properties.

Document metadata stores essential information about a KDDB document including its UUID, version, source information, labels, and custom properties.

## Commands

### Get Metadata

Retrieve all document metadata or a specific key:

```bash theme={null}
# Get all metadata
kdx document metadata get <file.kddb>

# Get a specific key
kdx document metadata get <file.kddb> <key>
```

**Example - All metadata:**

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

```text theme={null}
┌──────────┬─────────────────────────────────────────────────────┐
│  FIELD   │                       VALUE                         │
├──────────┼─────────────────────────────────────────────────────┤
│ uuid     │ e25dab60-cbdf-499f-857e-ff9c82a19d87                │
│ version  │ 6.0.0                                               │
│ labels   │ []                                                  │
│ source   │ {}                                                  │
│ metadata │ {"connector":"folder","source_path":"/docs/invoice"}│
└──────────┴─────────────────────────────────────────────────────┘
```

**Example - Specific key:**

```bash theme={null}
kdx document metadata get invoice.kddb source.connector
```

```text theme={null}
┌──────────────────┬────────┐
│      FIELD       │ VALUE  │
├──────────────────┼────────┤
│ source.connector │ folder │
└──────────────────┴────────┘
```

### Set Metadata

Set or update a metadata key:

```bash theme={null}
kdx document metadata 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 metadata set invoice.kddb custom_field '"my value"'

# Set a number
kdx document metadata set invoice.kddb priority '1'

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

# Set an object
kdx document metadata set invoice.kddb config '{"enabled": true, "threshold": 0.8}'

# Set an array
kdx document metadata set invoice.kddb tags '["invoice", "processed"]'
```

**Output:**

```text theme={null}
Set metadata key: custom_field
```

## Standard Metadata Fields

KDDB documents typically include these standard metadata fields:

| Field      | Description                | Example                                  |
| ---------- | -------------------------- | ---------------------------------------- |
| `uuid`     | Unique document identifier | `"e25dab60-cbdf-499f-857e-ff9c82a19d87"` |
| `version`  | KDDB format version        | `"6.0.0"`                                |
| `labels`   | Document labels/tags       | `["invoice", "2024"]`                    |
| `source`   | Source information         | `{"connector": "folder"}`                |
| `metadata` | Nested metadata object     | `{"title": "Invoice #123"}`              |
| `mixins`   | Applied document mixins    | `["spatial"]`                            |

## Output Formats

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

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

# YAML output
kdx document metadata get invoice.kddb -o yaml
```

**JSON output example:**

```json theme={null}
{
  "uuid": "e25dab60-cbdf-499f-857e-ff9c82a19d87",
  "version": "6.0.0",
  "labels": [],
  "source": {},
  "metadata": {
    "connector": "folder",
    "source_path": "/docs/invoice.pdf",
    "title": "Invoice #123"
  }
}
```

## Use Cases

### Document Identification

Get the unique identifier for a document:

```bash theme={null}
# Get UUID
kdx document metadata get invoice.kddb -o json | jq -r '.uuid'
```

### Update Custom Properties

Add custom metadata for tracking:

```bash theme={null}
# Add processing timestamp
kdx document metadata set invoice.kddb processed_at '"2024-01-15T10:30:00Z"'

# Add reviewer info
kdx document metadata set invoice.kddb reviewer '"john.doe@company.com"'
```

### Batch Metadata Updates

Update metadata across multiple documents:

```bash theme={null}
# Add a label to all documents
for kddb in *.kddb; do
  kdx document metadata set "$kddb" batch_id '"batch-2024-01"'
done
```

### Scripting Integration

Use metadata in automated workflows:

```bash theme={null}
# Get document UUID for API calls
UUID=$(kdx document metadata get invoice.kddb -o json | jq -r '.uuid')
echo "Processing document: $UUID"

# Check document version
VERSION=$(kdx document metadata get invoice.kddb -o json | jq -r '.version')
if [[ "$VERSION" < "6.0.0" ]]; then
  echo "Warning: Old document format"
fi
```

### Export Metadata

Export metadata for documentation or reporting:

```bash theme={null}
# Export as JSON
kdx document metadata get invoice.kddb -o json > invoice_metadata.json

# Export as YAML
kdx document metadata get invoice.kddb -o yaml > invoice_metadata.yaml
```

## Notes

<Note>
  Metadata is stored in a compressed format (MessagePack) in older KDDB files and as JSON in newer versions. The CLI handles both formats transparently.
</Note>

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

<Tip>
  The `uuid` and `version` fields are typically read-only and managed by the document creation process. Avoid modifying these unless you understand the implications.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="SDK: Metadata" icon="code" href="/sdk/metadata">
    Work with metadata programmatically
  </Card>

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