CLI reference

The installed nirs4all command exposes task groups. Python API names do not automatically become top-level CLI commands.

Group	Purpose	Discover commands
`workflow`	Native run, predict, retrain, export and reload	`nirs4all workflow --help`
`results`	Checked experiment/result views	`nirs4all results --help`
`tuning`	Native search, resume and saved tuning state	`nirs4all tuning --help`
`dataset`	Load/inspect/validate datasets	`nirs4all dataset --help`
`config`	Validate configuration and portable pipeline definitions	`nirs4all config --help`
`workspace`	Initialize, query and manage workspace contents	`nirs4all workspace --help`
`artifacts`	Inspect stored artifacts	`nirs4all artifacts --help`

Native workflow commands

nirs4all workflow run dataset.json --components 1 2 --archive model.n4a
nirs4all workflow predict --archive model.n4a --input predict.json
nirs4all workflow retrain dataset.json saved-workflow --archive new-model.n4a
nirs4all workflow export saved-workflow copied-workflow
nirs4all workflow load saved-workflow

run/retrain read an IO JSON/YAML dataset declaration and publish a new archive plus native results. predict requires a JSON object with exactly x and sample_ids; it does not fit. load, retrain and export read the exported workflow directory. Optional --native-cli, --methods-library, --results-directory, --run-id and --output are available where shown by the operation’s help. JSON output destinations are new files and must not overlap archive/results publication destinations. See the downloadable input and full language lifecycle in 1. Run your first complete experiment.

Workspace commands

The nirs4all CLI provides workspace management commands for organizing experiments, querying results, and managing saved models.

Installation

The CLI is available after installing nirs4all:

pip install nirs4all

Usage

nirs4all workspace <command> [options]

Commands

`init` - Initialize Workspace

Create a new workspace with the standard directory structure.

Usage:

nirs4all workspace init <path>

Example:

nirs4all workspace init my_workspace

Output:

✓ Workspace initialized at: my_workspace
  Created:
    - store.sqlite (workspace database)
    - arrays/
    - artifacts/
    - exports/
    - library/

`list-runs` - List Runs

List all experimental runs in a workspace.

Usage:

nirs4all workspace list-runs [--workspace <path>]

Options:

--workspace: Workspace root directory (default: workspace)

Example:

nirs4all workspace list-runs --workspace my_workspace

Output:

Found 3 run(s):

  wheat_sample1_baseline
    Dataset: wheat

  corn_sample1
    Dataset: corn

`query-best` - Query Best Pipelines

Query the catalog for top-performing pipelines by a specific metric.

Usage:

nirs4all workspace query-best [options]

Options:

--workspace <path>: Workspace root (default: workspace)
--dataset <name>: Filter by dataset name
--metric <name>: Metric to sort by (default: test_score)
-n <number>: Number of results (default: 10)
--ascending: Sort ascending (lower is better)

Examples:

# Get top 10 by test_score
nirs4all workspace query-best --workspace my_workspace

# Get top 5 wheat models by validation score
nirs4all workspace query-best --workspace my_workspace --dataset wheat --metric val_score -n 5

# Get worst 3 models (ascending)
nirs4all workspace query-best --workspace my_workspace -n 3 --ascending

Output:

✓ Loaded 142 predictions from catalog

Top 10 pipelines by test_score:
================================================================================

prediction_id                          dataset_name  config_name      test_score
a1b2c3d4-5678-90ab-cdef-1234567890ab  wheat_sample1  advanced_pls     0.5234
e5f6g7h8-9012-34ab-cdef-5678901234cd  wheat_sample1  optimized_rf     0.5198
...

`filter` - Filter Predictions

Filter predictions by multiple criteria (dataset, score thresholds).

Usage:

nirs4all workspace filter [options]

Options:

--workspace <path>: Workspace root (default: workspace)
--dataset <name>: Filter by dataset name
--test-score <value>: Minimum test score
--train-score <value>: Minimum train score
--val-score <value>: Minimum validation score

Examples:

# Find all predictions with test_score >= 0.50
nirs4all workspace filter --workspace my_workspace --test-score 0.50

# Find wheat predictions with good train and test scores
nirs4all workspace filter --workspace my_workspace --dataset wheat --test-score 0.45 --train-score 0.40

# Find predictions meeting all criteria
nirs4all workspace filter --workspace my_workspace --test-score 0.50 --val-score 0.48 --train-score 0.45

Output:

Found 23 predictions matching criteria

prediction_id                          dataset_name  test_score  train_score  val_score
a1b2c3d4-5678-90ab-cdef-1234567890ab  wheat_sample1  0.5234     0.4876       0.5012
...

`stats` - Catalog Statistics

Show summary statistics for the catalog.

Usage:

nirs4all workspace stats [options]

Options:

--workspace <path>: Workspace root (default: workspace)
--metric <name>: Metric for statistics (default: test_score)

Example:

nirs4all workspace stats --workspace my_workspace --metric test_score

Output:

Catalog Statistics
============================================================

Total predictions: 142
Datasets: 3
  - wheat_sample1: 58 predictions
  - corn_sample1: 45 predictions
  - barley_sample1: 39 predictions

test_score statistics:
  Min:    0.3245
  Max:    0.5234
  Mean:   0.4512
  Median: 0.4498
  Std:    0.0456

`list-library` - List Library Items

List templates and saved models in the library.

Usage:

nirs4all workspace list-library [--workspace <path>]

Options:

--workspace: Workspace root directory (default: workspace)

Example:

nirs4all workspace list-library --workspace my_workspace

Output:

Templates: 2
  - baseline_pls: Baseline PLS configuration
  - advanced_rf: Random Forest with feature selection

Filtered pipelines: 5
  - wheat_experiment_001: First wheat experiment
  - corn_baseline_v1: Baseline model for corn

Full pipelines: 3
  - production_wheat_v1: Production-ready wheat model
  - deployment_corn_v2: Corn model for deployment

Full runs: 1
  - wheat_baseline_complete: Complete baseline experiment

Programmatic Usage

All CLI commands can also be used programmatically:

from nirs4all.pipeline.storage import WorkspaceStore

# Initialize workspace
store = WorkspaceStore("my_workspace")

# Query best predictions
top = store.top_predictions(n=10, metric="test_score")

See examples/user/06_deployment/U03_workspace_management.py for a complete example.

Workflow Example

# 1. Initialize workspace
nirs4all workspace init my_project

# 2. Run experiments (using Python API)
# ... your training code ...

# 3. Query results
nirs4all workspace query-best --workspace my_project -n 5

# 4. Filter good models
nirs4all workspace filter --workspace my_project --test-score 0.50

# 5. View statistics
nirs4all workspace stats --workspace my_project

# 6. Check saved models
nirs4all workspace list-library --workspace my_project

Conformal and Robustness Audit Commands

The CLI can inspect stored conformal/robustness artifacts and republish verified robustness reports. These commands are read-only unless an explicit --output path is provided.

nirs4all workspace conformal list --workspace workspace --json
nirs4all workspace conformal show pls-moisture-conformal --workspace workspace --json
nirs4all workspace conformal show pls-moisture-conformal \
  --workspace workspace \
  --as-predict-result \
  --json
nirs4all workspace tuning export pls-moisture-hpo \
  --workspace workspace \
  --format summary \
  --output artifacts/tuning/pls-moisture/summary.json
nirs4all workspace conformal predict pls-moisture-conformal \
  --workspace workspace \
  --y-pred "13.0,14.0" \
  --sample-ids "sample-003,sample-004" \
  --json

workspace conformal predict applies an already stored calibrator to already computed point predictions. It does not train, refit, recalibrate, or mutate the workspace.

workspace conformal show --as-predict-result --json converts the stored CalibratedRunResult through calibrated.to_predict_result() and emits the public prediction payload: point predictions, materialized intervals, calibrated_result_fingerprint, calibration_replay_source, and tuning_calibration_source. Use this form for bindings, Studio and notebook diagnostics that need the same accessors as nirs4all.predict().

workspace tuning export --format summary emits the compact nirs4all.tuning.summary contract used by CI, bindings, Studio/Web, and dashboards. Use --format json when the full verified TuningResult evidence tape is required.

nirs4all workspace robustness list --workspace workspace --json
nirs4all workspace robustness show pls-moisture-robustness --workspace workspace --json
nirs4all workspace robustness evidence --workspace workspace --dataset wheat --json
nirs4all workspace robustness from-prediction \
  --workspace workspace \
  --prediction-id pred-001 \
  --y-true "1.0,2.0,3.0" \
  --scenarios-json '[{"kind":"spectral_offset","severity":0.01}]' \
  --save-to-workspace \
  --workspace-robustness-id pred-001-spectral-audit \
  --format summary \
  --output artifacts/robustness/pred-001/summary.json
nirs4all workspace robustness export pls-moisture-robustness \
  --workspace workspace \
  --format summary \
  --output artifacts/robustness/pls-moisture/summary.json

workspace robustness evidence inspects stored prediction rows with load_arrays=True and reports the native PredictResult.spectral_replay_evidence_status diagnostic for each prediction. It is read-only: it never synthesizes X, spectra, or predictor bundles. Rows become ready_for_spectral_replay only when the prediction carries an actual row-aligned executable X/spectra matrix and a predictor_bundle/model_path; provenance markers such as prediction_arrays.X remain diagnostic metadata unless the array is also loaded from the workspace sidecar. When the stored prediction also carries native conformal provenance, JSON output includes calibration_replay_source and tuning_calibration_source from the same PredictResult conversion so CI, bindings and Studio can audit replay/calibration boundaries without parsing raw workspace rows.

workspace robustness from-prediction is the executable CLI bridge from one stored prediction row to a RobustnessReport. It loads the row through nirs4all.robustness_from_workspace_prediction(), so executable X/spectra and saved predictor_bundle/model_path evidence are consumed as spectral/OOD defaults when present. --y-true accepts comma-separated targets; --y-true-json accepts the same values as JSON. --scenarios-json, --metadata-json, --slice-by, and --seed map directly to nirs4all.robustness(). Use --save-to-workspace with --workspace-robustness-id to persist the generated report back to the same workspace linked to the prediction id. Output formats match workspace robustness export: json, summary, markdown, html, parquet, and artifacts.

workspace robustness export --format summary emits the compact summary.json contract used by CI, bindings, Studio/Web, and dashboards. Other formats are json, markdown, html, parquet, and artifacts.

Verified report files or artifact directories can also be republished without a workspace:

nirs4all robustness-report artifacts/robustness/pls-moisture \
  --format markdown \
  --output artifacts/robustness/pls-moisture/report.md

nirs4all robustness-report artifacts/robustness/pls-moisture/report.json \
  --format summary \
  --output artifacts/robustness/pls-moisture/summary.json

nirs4all robustness-summary-schema --output artifacts/robustness-summary.schema.json
nirs4all tuning-summary-schema --output artifacts/tuning-summary.schema.json
nirs4all keyword-registry --output artifacts/keyword-registry.json
nirs4all tuning-space --input tuning.json --output artifacts/tuning-space.json
nirs4all tuning-space --schema --output artifacts/tuning-space.schema.json

The schema command publishes the JSON Schema for RobustnessReport.summary_artifact() and bundle summary.json payloads. Static consumers should validate the schema version and fingerprint before displaying release cards or Studio result cards. tuning-summary-schema does the same for TuningResult.summary_artifact() and HPO summary.json cards. keyword-registry publishes machine-readable keyword effects for forms and Studio, including HPO controls such as run.tuning.force_params, whose changes field records trial_sequence, candidate_fit, and selection. The exported registry also carries the strict JSON-native schemas for tuning, conformal, prediction, robustness and workspace metadata, so external forms can reject non-canonical metadata before invoking Python helpers. tuning-space publishes the same JSON-native nirs4all.tuning.ordered_search_space artifact as nirs4all.inspect_tuning_space(...): canonical dotted paths, ordered parameters, decoded ParameterPatch force params, fingerprint, and tuning_fingerprint. It reads a tuning JSON payload from --input or --tuning and does not execute a pipeline. tuning-space --schema publishes the matching JSON Schema for bindings, CLI validators and Studio forms.

Notes

All commands default to workspace/ if --workspace is not specified
The catalog must be populated using Predictions.archive_to_catalog() before querying
Use --help with any command for detailed options: nirs4all workspace <command> --help

CLI reference

Native workflow commands

Workspace commands

Installation

Usage

Commands

init - Initialize Workspace

list-runs - List Runs

query-best - Query Best Pipelines

filter - Filter Predictions

stats - Catalog Statistics

list-library - List Library Items

Programmatic Usage

Workflow Example

Conformal and Robustness Audit Commands

Notes

`init` - Initialize Workspace

`list-runs` - List Runs

`query-best` - Query Best Pipelines

`filter` - Filter Predictions

`stats` - Catalog Statistics

`list-library` - List Library Items