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

# Store Commands

> Use kdx store commands to upload documents, monitor processing, and manage document stores from the command line on the Kodexa AI Platform.

# Store Commands

The `kdx store` command provides operational commands for document stores. Use it when you need to upload source documents, watch processing progress, inspect store health, or rebuild store indexes.

Document stores are where document families enter a project. The CLI is useful for scripted test uploads, smoke tests after an Activity Plan change, and operational checks in non-production environments.

## Available Commands

| Command   | Description                                               |
| --------- | --------------------------------------------------------- |
| `upload`  | Upload a file to a document store                         |
| `watch`   | Monitor a document family until it reaches a target label |
| `stats`   | Show store statistics                                     |
| `reindex` | Trigger store reindexing                                  |

## Upload Documents

Upload a PDF, image, or document to a document store. The platform creates a document family and queues it for the store's configured processing.

```bash theme={null}
kdx store upload <store-ref> <file-path>
```

### Parameters

| Parameter   | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `store-ref` | Store reference in the form `org/store-slug` or `org/store-slug:version` |
| `file-path` | Path to the file to upload                                               |

### Examples

```bash theme={null}
# Upload a PDF to a project processing store
kdx store upload acme/ap-processing ./invoice.pdf

# Upload with an explicit store version
kdx store upload acme/ap-processing:1.0.0 /path/to/invoice.pdf
```

### Output

```text theme={null}
Uploading invoice.pdf to store acme/ap-processing...
✓ Document family created: a700ca3e-38e7-4e63-8974-59c2e9058cf3
```

The command returns the document family ID which you can use with `kdx store watch` or `kdx document-family data`.

## Watch Processing Progress

Monitor a document family until it reaches a label such as `PREPARED`, `LABELED`, or `PROCESSED`. This is useful in local smoke tests and CI jobs that upload a document and need to wait for processing to finish before exporting data.

```bash theme={null}
kdx store watch <document-family-id> [flags]
```

### Flags

| Flag              | Default     | Description              |
| ----------------- | ----------- | ------------------------ |
| `--label`         | `PROCESSED` | Target label to wait for |
| `--timeout`       | `600`       | Timeout in seconds       |
| `--poll-interval` | `3`         | Poll interval in seconds |

### Processing Labels

Labels depend on the store and processing design. Common labels include:

| Label        | Description                                   |
| ------------ | --------------------------------------------- |
| `PREPARED`   | Document parsed and prepared                  |
| `FIRST-PASS` | Initial extraction or classification complete |
| `LABELED`    | Data labeling complete                        |
| `PROCESSED`  | Final transformation complete                 |

### Examples

```bash theme={null}
# Watch until fully processed
kdx store watch a700ca3e-38e7-4e63-8974-59c2e9058cf3

# Watch for a specific label
kdx store watch a700ca3e-38e7-4e63-8974-59c2e9058cf3 --label LABELED

# Custom timeout and poll interval
kdx store watch a700ca3e-38e7-4e63-8974-59c2e9058cf3 --timeout 900 --poll-interval 5
```

### Output

```text theme={null}
Watching document family a700ca3e-38e7-4e63-8974-59c2e9058cf3 for label: PROCESSED
Timeout: 900s, Poll interval: 5s

[  0s] RUNNING    | Labels: none | PDF Parser
[ 42s] RUNNING    | Labels: none | OCR
[ 73s] RUNNING    | Labels: none | Invoice extraction
[389s] RUNNING    | Labels: FIRST-PASS | Validation
[472s] RUNNING    | Labels: LABELED | Transformation
[523s] RUNNING    | Labels: PROCESSED

✓ Document family reached label: PROCESSED
```

The command also detects failed executions and exits with a non-zero status.

```text theme={null}
[ 24s] FAILED     | Labels: none | OCR: Unable to build document

✗ Processing failed: OCR: Unable to build document
```

## Store Statistics

View statistics for a document store. This command is useful for operational checks and dashboards where you want a quick CLI view of document count, storage size, index status, and any performance metrics the server returns.

```bash theme={null}
kdx store stats <store-name>
```

### Example

```bash theme={null}
kdx store stats ap-processing
```

### Output

```text theme={null}
Store: ap-processing
====================
Documents: 150
Storage Size: 2.5 GB
Index Status: READY
```

## Reindex Store

Trigger a reindexing operation for a store. Reindexing is an administrative operation used when store search or derived indexes need to be rebuilt.

```bash theme={null}
kdx store reindex <store-name> [flags]
```

### Flags

| Flag      | Description                               |
| --------- | ----------------------------------------- |
| `--force` | Force reindex even if already in progress |

### Examples

```bash theme={null}
# Standard reindex
kdx store reindex ap-processing

# Force a reindex even if another reindex is in progress
kdx store reindex ap-processing --force
```

### Output

```text theme={null}
Reindex triggered for store 'ap-processing'
Job ID: 4d8a4a7f-8d56-4c49-9d2f-1d4d21f1c20d
```

## Common Workflows

### Smoke Test a Store

```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
```

### Inspect Store Health

```bash theme={null}
kdx store stats ap-processing
kdx get document-families --filter "documentStore.slug:'ap-processing'" -o table
```