Skip to content

Complete CLI workflow

Goal: generate, inspect, validate and archive without writing Python.

Prerequisites: Installation. Commands run from the repository root. Drop the uv run prefix if you have activated .venv or installed the wheel elsewhere.

A runnable version is examples/06_cli_usage.py.

1. Confirm the installation

uv run openauc version

0.1.0a1

2. See what can be read

uv run openauc formats

aucx  AUCX archive
  suffixes:    .aucx
  layouts:     zip-of-parts (JSON metadata + NumPy .npy arrays)
  limitations: format version 1.0 only; archives are never migrated silently
               every checksum is verified before a model is built
               checksums establish integrity, not authenticity
  docs:        docs/formats/aucx.md
generic-long  Generic long-format delimited
  ...

Machine-readable:

uv run openauc formats --json | jq -r '.formats[].format_id'

3. Get some data

Either use the repository's demo data at examples/data/demo_experiment, or generate a dataset:

uv run openauc generate work/demo --scenario moving-boundary --scans 12 --points 200 --seed 7

wrote work/demo
  scenario: moving-boundary  seed: 7  scans: 12
  note: illustrative synthetic data; not a physically validated simulation

That writes work/demo/manifest.json and work/demo/scans.csv.

4. Inspect

uv run openauc inspect work/demo

Prints the structural summary. For scripting:

uv run openauc inspect work/demo --json | jq '.n_scans, .total_valid_observations'

12
2400

5. Validate

uv run openauc validate work/demo
echo "exit code: $?"

structural validation: OK (no issues)

note: structural validation only; no claim is made about scientific validity
or data quality.
exit code: 0

Add readiness:

uv run openauc validate work/demo --readiness

6. Convert to AUCX

uv run openauc convert work/demo work/demo.aucx

wrote work/demo.aucx (18244 bytes)

Running it again refuses, with exit code 3:

uv run openauc convert work/demo work/demo.aucx
echo "exit code: $?"

error: work/demo.aucx already exists; pass --overwrite to replace it
exit code: 3

7. Verify the archive

uv run openauc validate work/demo.aucx

archive integrity: OK (work/demo.aucx)
structural validation: OK (no issues)
...

Integrity is checked first. A corrupt container stops the run with exit code 2 before the experiment is examined.

Integrity is not authenticity

A verified archive is one whose bytes are unchanged since it was written. AUCX carries no signature and proves nothing about who produced it.

8. Script it

Exit codes make the CLI composable:

#!/usr/bin/env bash
set -euo pipefail

for dir in data/*/; do
    if uv run openauc validate "$dir" >/dev/null 2>&1; then
        uv run openauc convert "$dir" "archives/$(basename "$dir").aucx" --overwrite
        echo "archived $dir"
    else
        echo "SKIPPED (validation failed): $dir" >&2
    fi
done
Code Meaning
0 Success; where validation ran, it passed
1 Structural validation failed
2 Input, parsing, archive or configuration error
3 Output exists and --overwrite was not given

Details: Exit codes.

Common failure modes

Symptom Cause Fix
command not found: openauc Not in the project environment Use uv run, or activate .venv
No such command 'generate' Stale checkout git pull && uv sync --all-groups
exit 2 on a directory No manifest, or unreadable data openauc inspect for the message
exit 3 Output exists Add --overwrite

Next step