BNNR

CLI Reference

What you will find here

Command reference for python3 -m bnnr aligned to src/bnnr/cli.py.

When to use this page

Use this for no-code workflows: training, report reading, dashboard replay/export.

Entry point

python3 -m bnnr --help

demo

python3 -m bnnr demo

Zero-config onboarding run — no flags, no YAML.

  • Downloads CIFAR-10 automatically on first use.
  • Trains a small demo CNN (not ResNet-18) with preset demo (saliency-guided ICD + ChurchNoise).
  • Sample limits: 128 train / 64 val; m_epochs=1, max_iterations=1, XAI enabled.
  • Starts the live dashboard and opens it in your browser (same as --with-dashboard on train).
  • Writes artifacts under reports/ and checkpoints/; after training (before the dashboard wait loop) prints paths to the JSON report and reports/<run>/artifacts/xai/ heatmaps when present.

For an interactive wizard with prompts, use quickstart instead.

quickstart

python3 -m bnnr quickstart [OPTIONS]

Interactive zero-config demo: prompts for dataset, preset, and dashboard, then runs training with built-in defaults and sample limits (128 train / 64 val).

Options: --dashboard-port, --no-auto-open.

train

python3 -m bnnr train [OPTIONS]

Omit --config to use built-in quickstart defaults (m_epochs=3, max_iterations=2, device=auto, etc.).

Supported datasets

Classification (built-in single-label demos):

  • mnist
  • fashion_mnist
  • cifar10
  • stl10
  • imagefolder

Object detection (requires task: detection in your YAML and a matching config; see Detection):

  • coco_mini — COCO-style layout under --data-path (train2017/val2017 or train/val, plus annotations/).
  • yolo — Ultralytics-style --data-path pointing at data.yaml or its parent directory.

Multi-label classification

bnnr train with mnist, fashion_mnist, cifar10, stl10, or imagefolder always builds single-label pipelines (CrossEntropyLoss, one class index per sample). Setting task: multilabel in your config YAML does not change that behavior. For multi-label, use the Python API (Golden Path) or the scripts under examples/multilabel/ (Examples Guide).

Main options

  • --config, -c (optional YAML; omit for built-in defaults)
  • --dataset
  • --data-dir
  • --data-path (required for imagefolder, coco_mini, and yolo)
  • --output, -o
  • --device, -d (cuda, cpu, auto)
  • --epochs, -e
  • --seed, -s
  • --no-xai
  • --augmentation-preset, --preset (auto, light, standard, aggressive, gpu, none; unknown names fall back to auto with a warning)
  • --with-dashboard / --without-dashboard
  • --dashboard-port
  • --no-auto-open
  • --dashboard-token
  • --batch-size
  • --max-train-samples
  • --max-val-samples
  • --num-classes (for imagefolder)

Behavior notes

  • --with-dashboard (default): starts live dashboard server and keeps process alive.
  • --without-dashboard: no live server; good for one-shot runs.
  • CLI keeps event logging enabled so dashboard export works after training.

Examples

# Zero-config CIFAR-10 (built-in defaults)
python3 -m bnnr train --dataset cifar10 --preset light --with-dashboard
 
# CIFAR-10 with custom YAML
python3 -m bnnr train \
  --config examples/configs/classification/cifar10_example.yaml \
  --dataset cifar10 \
  --preset light \
  --without-dashboard
 
# ImageFolder
python3 -m bnnr train \
  --config examples/configs/classification/imagefolder_example.yaml \
  --dataset imagefolder \
  --data-path /path/to/dataset

analyze

python3 -m bnnr analyze --model PATH --data PATH_OR_DATASET --output DIR [OPTIONS]

Run standalone diagnostics on a trained model (no training): metrics, XAI, data quality, failure analysis, patterns, recommendations. Writes analysis_report.json and report.html under --output.

Required: --model (checkpoint .pt), --data (directory or dataset name: mnist, fashion_mnist, cifar10, stl10), --output.

Options: --task (classification or multilabel only; detection is not supported by analyze), --config, --max-worst, --no-xai, --no-data-quality, --device, --batch-size, --cv-folds, --xai-samples, --summary/--no-summary.

On Windows terminals with encoding issues, set PYTHONUTF8=1 and PYTHONIOENCODING=utf-8 before running bnnr analyze.

See analyze.md for details and examples.

report

python3 -m bnnr report path/to/report.json --format summary
python3 -m bnnr report path/to/report.json --format json
python3 -m bnnr report path/to/report.json --format json --output report_payload.json

Notes:

  • --format html is intentionally rejected in current CLI.
  • --output writes rendered report output to file (summary text or JSON payload).
  • Use dashboard export for static HTML output.

Dashboard commands

python3 -m bnnr dashboard serve --run-dir reports --port 8080
python3 -m bnnr dashboard export --run-dir reports/run_YYYYMMDD_HHMMSS --out exported_dashboard

dashboard serve options:

  • --run-dir
  • --port
  • --frontend-dist
  • --token (or env BNNR_DASHBOARD_TOKEN)

dashboard export options:

  • --run-dir (required)
  • --out (required)
  • --frontend-dist

Dashboard usage notes (important)

  • dashboard serve prints both Local URL and Network URL plus terminal QR code.
  • Open Local URL on desktop first, then use QR from phone on the same network.
  • For secured controls, use --token (or BNNR_DASHBOARD_TOKEN).
  • For production workflow details (pause/resume, mobile access, export), see dashboard.md.

Utility commands

python3 -m bnnr list-augmentations
python3 -m bnnr list-augmentations --verbose
python3 -m bnnr list-presets
python3 -m bnnr list-datasets
python3 -m bnnr version