> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucitra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

# Command Reference

Complete reference for all Lucitra CLI commands. Every command accepts the global flags `--api-key (-k)` and `--api-url` to override stored configuration.

## lucitra upload

Upload a dataset file to Lucitra. Creates a new dataset record and uploads the file via a signed URL.

```bash theme={null}
lucitra upload <file> --name <name> [flags]
```

| Parameter       | Type   | Required | Description                                                               |
| --------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `<file>`        | path   | Yes      | Path to the dataset file to upload                                        |
| `--name, -n`    | string | Yes      | Human-readable name for the dataset                                       |
| `--project, -p` | UUID   | No       | Project to upload into (uses default if set)                              |
| `--format, -f`  | enum   | No       | Dataset format: `coco`, `kitti`, `nuscenes`, `custom` (default: `custom`) |
| `--api-key, -k` | string | No       | Override stored API key                                                   |
| `--api-url`     | string | No       | Override stored API URL                                                   |

<CodeGroup>
  ```bash COCO format theme={null}
  lucitra upload ./annotations.json --name "warehouse-v3" --format coco
  ```

  ```bash nuScenes format theme={null}
  lucitra upload ./nuscenes-mini.tar.gz --name "highway-scenes" --format nuscenes --project 9f1a2b3c-...
  ```

  ```bash Custom format theme={null}
  lucitra upload ./my-data.zip --name "custom-pipeline-output"
  ```
</CodeGroup>

<Note>
  The CLI automatically handles multipart uploads for large files. There is no need to split files manually.
</Note>

***

## lucitra validate

Run a validation job against a dataset. The CLI polls for progress and displays results when the job completes.

```bash theme={null}
lucitra validate --dataset <uuid> [flags]
```

| Parameter       | Type    | Required | Description                                                                     |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------- |
| `--dataset, -d` | UUID    | Yes      | Dataset to validate                                                             |
| `--type, -t`    | enum    | No       | Validation type: `coverage`, `physics`, `sim-to-real`, `full` (default: `full`) |
| `--timeout`     | integer | No       | Maximum wait time in seconds (default: `300`)                                   |
| `--json`        | boolean | No       | Output raw JSON instead of formatted summary                                    |
| `--api-key, -k` | string  | No       | Override stored API key                                                         |
| `--api-url`     | string  | No       | Override stored API URL                                                         |

<CodeGroup>
  ```bash Full validation theme={null}
  lucitra validate --dataset 9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
  ```

  ```bash Coverage only theme={null}
  lucitra validate -d 9f1a2b3c-... --type coverage
  ```

  ```bash JSON output for scripting theme={null}
  lucitra validate -d 9f1a2b3c-... --json > report.json
  ```
</CodeGroup>

The CLI displays a live progress indicator while the validation runs:

```
Validating dataset "warehouse-v3"...
  ████████████████████░░░░░░░░░░  67%  Running physics checks...

Validation Complete
───────────────────────────────────────
  Overall Score      82/100
  Coverage           78/100
  Physics            91/100
  Distribution       84/100
  Sim-to-Real        75/100

  Report ID: rpt_a1b2c3d4e5f6
  Full report: https://app.lucitra.io/reports/rpt_a1b2c3d4e5f6
```

<Warning>
  If the validation does not complete within the `--timeout` window, the CLI exits with code 1. The validation job continues running server-side. Use `lucitra report` to retrieve results later.
</Warning>

***

## lucitra datasets

List datasets in a project.

```bash theme={null}
lucitra datasets [flags]
```

| Parameter       | Type    | Required | Description                             |
| --------------- | ------- | -------- | --------------------------------------- |
| `--project, -p` | UUID    | No       | Filter by project (uses default if set) |
| `--json`        | boolean | No       | Output raw JSON instead of table        |
| `--api-key, -k` | string  | No       | Override stored API key                 |
| `--api-url`     | string  | No       | Override stored API URL                 |

```bash theme={null}
lucitra datasets --project 9f1a2b3c-...
```

Output:

```
NAME                FORMAT     SCENES    SIZE       UPLOADED
warehouse-v3        coco       1,247     342 MB     2 hours ago
highway-scenes      nuscenes   850       1.2 GB     3 days ago
factory-floor-v1    kitti      3,100     890 MB     1 week ago
```

***

## lucitra report

Fetch and display a validation report.

```bash theme={null}
lucitra report <report-id> [flags]
```

| Parameter       | Type   | Required | Description                                                         |
| --------------- | ------ | -------- | ------------------------------------------------------------------- |
| `<report-id>`   | UUID   | Yes      | The report ID to retrieve                                           |
| `--format, -f`  | enum   | No       | Output format: `summary`, `json`, `pdf` (default: `summary`)        |
| `--output, -o`  | path   | No       | File path to write output (required for `pdf`, optional for `json`) |
| `--api-key, -k` | string | No       | Override stored API key                                             |
| `--api-url`     | string | No       | Override stored API URL                                             |

<CodeGroup>
  ```bash Summary (default) theme={null}
  lucitra report rpt_a1b2c3d4e5f6
  ```

  ```bash JSON to file theme={null}
  lucitra report rpt_a1b2c3d4e5f6 --format json --output ./report.json
  ```

  ```bash PDF export theme={null}
  lucitra report rpt_a1b2c3d4e5f6 --format pdf --output ./validation-report.pdf
  ```
</CodeGroup>

<Tip>
  The `pdf` format generates a report suitable for compliance documentation and stakeholder review. It includes score breakdowns, flagged issues, and remediation guidance.
</Tip>

***

## lucitra config

Manage CLI configuration.

```bash theme={null}
lucitra config <action> [key] [value]
```

| Parameter  | Type    | Required        | Description                                    |
| ---------- | ------- | --------------- | ---------------------------------------------- |
| `<action>` | enum    | Yes             | One of: `set`, `get`, `list`                   |
| `[key]`    | string  | For `set`/`get` | Config key: `api-key`, `api-url`, `project-id` |
| `[value]`  | string  | For `set`       | Value to store                                 |
| `--json`   | boolean | No              | Output in JSON format                          |

<CodeGroup>
  ```bash Set a value theme={null}
  lucitra config set api-key luci_your_api_key
  ```

  ```bash Get a value theme={null}
  lucitra config get api-url
  ```

  ```bash List all values theme={null}
  lucitra config list
  ```

  ```bash List as JSON theme={null}
  lucitra config list --json
  ```
</CodeGroup>

***

## Example Workflows

### Upload and validate a dataset

<Steps>
  <Step title="Upload your data">
    ```bash theme={null}
    lucitra upload ./coco-annotations.json \
      --name "parking-lot-v2" \
      --format coco \
      --project 9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    ```

    The CLI prints the new dataset ID on success:

    ```
    Dataset created: ds_x7y8z9a0b1c2
    Upload complete (342 MB)
    ```
  </Step>

  <Step title="Run validation">
    ```bash theme={null}
    lucitra validate --dataset ds_x7y8z9a0b1c2 --type full
    ```
  </Step>

  <Step title="Export the report">
    ```bash theme={null}
    lucitra report rpt_a1b2c3d4e5f6 --format pdf --output ./validation-report.pdf
    ```
  </Step>
</Steps>

### CI/CD quality gate

Use the `--json` flag and a script to fail your pipeline when scores drop below a threshold:

```bash theme={null}
#!/bin/bash
set -e

# Upload and validate
lucitra upload ./data.zip --name "ci-$(date +%s)" --format coco
RESULT=$(lucitra validate -d "$DATASET_ID" --json)

# Check overall score
SCORE=$(echo "$RESULT" | jq '.overall_score')
if (( $(echo "$SCORE < 80" | bc -l) )); then
  echo "Validation failed: overall score $SCORE is below threshold 80"
  exit 1
fi

echo "Validation passed with score $SCORE"
```

### Quick coverage check

When you only need to verify scenario coverage without running the full validation suite:

```bash theme={null}
lucitra validate -d ds_x7y8z9a0b1c2 --type coverage --json | jq '.scores.coverage'
```