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.

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

lucitra upload ./annotations.json --name "warehouse-v3" --format coco

lucitra upload ./nuscenes-mini.tar.gz --name "highway-scenes" --format nuscenes --project 9f1a2b3c-...

lucitra upload ./my-data.zip --name "custom-pipeline-output"

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

lucitra validate

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

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

lucitra validate --dataset 9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c

lucitra validate -d 9f1a2b3c-... --type coverage

lucitra validate -d 9f1a2b3c-... --json > report.json

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

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.

lucitra datasets

List datasets in a project.

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

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.

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

lucitra report rpt_a1b2c3d4e5f6

lucitra report rpt_a1b2c3d4e5f6 --format json --output ./report.json

lucitra report rpt_a1b2c3d4e5f6 --format pdf --output ./validation-report.pdf

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

lucitra config

Manage CLI configuration.

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

lucitra config set api-key luci_your_api_key

lucitra config get api-url

lucitra config list

lucitra config list --json

Example Workflows

Upload and validate a dataset

Upload your data

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)

Run validation

lucitra validate --dataset ds_x7y8z9a0b1c2 --type full

Export the report

lucitra report rpt_a1b2c3d4e5f6 --format pdf --output ./validation-report.pdf

CI/CD quality gate

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

#!/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:

lucitra validate -d ds_x7y8z9a0b1c2 --type coverage --json | jq '.scores.coverage'

Core

Integrations

Tools

Commands

Command Reference

lucitra upload

lucitra validate

lucitra datasets

lucitra report

lucitra config

Example Workflows

Upload and validate a dataset

CI/CD quality gate

Quick coverage check

​Command Reference

​lucitra upload

​lucitra validate

​lucitra datasets

​lucitra report

​lucitra config

​Example Workflows

​Upload and validate a dataset

​CI/CD quality gate

​Quick coverage check

Command Reference

lucitra upload

lucitra validate

lucitra datasets

lucitra report

lucitra config

Example Workflows

Upload and validate a dataset

CI/CD quality gate

Quick coverage check