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 < fil e > --name < nam e > [flags]
Parameter Type Required Description <file>path Yes Path to the dataset file to upload --name, -nstring Yes Human-readable name for the dataset --project, -pUUID No Project to upload into (uses default if set) --format, -fenum No Dataset format: coco, kitti, nuscenes, custom (default: custom) --api-key, -kstring No Override stored API key --api-urlstring No Override stored API URL
COCO format
nuScenes format
Custom format
lucitra upload ./annotations.json --name "warehouse-v3" --format coco
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 < uui d > [flags]
Parameter Type Required Description --dataset, -dUUID Yes Dataset to validate --type, -tenum No Validation type: coverage, physics, sim-to-real, full (default: full) --timeoutinteger No Maximum wait time in seconds (default: 300) --jsonboolean No Output raw JSON instead of formatted summary --api-key, -kstring No Override stored API key --api-urlstring No Override stored API URL
Full validation
Coverage only
JSON output for scripting
lucitra validate --dataset 9f1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
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.
Parameter Type Required Description --project, -pUUID No Filter by project (uses default if set) --jsonboolean No Output raw JSON instead of table --api-key, -kstring No Override stored API key --api-urlstring 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-i d > [flags]
Parameter Type Required Description <report-id>UUID Yes The report ID to retrieve --format, -fenum No Output format: summary, json, pdf (default: summary) --output, -opath No File path to write output (required for pdf, optional for json) --api-key, -kstring No Override stored API key --api-urlstring No Override stored API URL
Summary (default)
JSON to file
PDF export
lucitra report rpt_a1b2c3d4e5f6
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 < actio n > [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 --jsonboolean No Output in JSON format
Set a value
Get a value
List all values
List as JSON
lucitra config set api-key luci_your_api_key
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'
