CLI Reference¶

The batteryproc command-line interface is the primary way to process battery data files. This page is a complete reference for all available flags and options.

For practical usage examples and common workflows, see the CLI Usage Guide.

Usage¶

batteryproc [-h] [-r] [-o OUTDIR] [options] inputs [inputs ...]

1. Input & Discovery¶

Flag	Description
`inputs`	Required. One or more data files (`.xlsx`, `.csv`, `.txt`, `.mpt`) or a directory containing them.
`-r`, `--recursive`	Recursively search subdirectories when processing a directory. Default: `False`.

2. Output & Saving¶

Flag	Description
`-o`, `--outdir <DIR>`	Directory where plots and results will be saved. Default: a `Results` folder next to the input file.
`--svg`	Save plots as `.svg` vector graphics in addition to `.png`. Default: `False`.
`--dpi <INT>`	Image resolution for PNG plots. Default: `300`.
`--no-progress`	Hide the progress bar (useful for scripts and CI). Default: `False`.
`--quiet`	Suppress non-critical warnings from the console. Default: `False`.
`--csv`	Export plot data as CSV files alongside plots. Mutually exclusive with `--csv-only`.
`--csv-only`	Export plot data as CSV files only — skip plot generation (faster). Mutually exclusive with `--csv`.

3. Metrics & Normalization¶

Flag	Description
`--metrics-config <FILE>`	YAML configuration file with metric settings.
`--mass-g <FLOAT>`	Active material mass (grams) for capacity normalization (mAh/g). Overrides auto-detection.
`--cell-weight-g <FLOAT>`	Total cell weight (grams) for energy normalization (Wh/kg).
`--prefer-file-metrics`	Use file-reported metrics if available and within tolerance. This is the default.
`--recompute-all`	Force recalculation of all metrics from raw data (ignores file-reported values).
`--metric-tolerance <FLOAT>`	Max relative difference for metric validation (e.g., `0.05` = 5%).
`--metric-tolerance-abs <FLOAT>`	Absolute tolerance for metric validation.

Note

--prefer-file-metrics and --recompute-all are mutually exclusive in the CLI. The argument parser will reject commands that specify both flags; choose at most one when running batteryproc. When using the Python API (ProcessOptions), if both options are set programmatically, recompute_all takes precedence and all metrics are recomputed from raw data, ignoring file-reported values.

4. Cycle Detection¶

See the Cycle Detection Guide for theory and the Cycle Detection Config Guide for YAML configuration.

Flag	Description
`--cycle-detection <METHOD>`	Detection method: `auto` (default), `step_type`, `current_sign`, or `legacy`.
`--cycle-config <FILE>`	YAML file with detection parameters.
`--current-threshold <AMPS>`	Current threshold to distinguish active steps from rest periods.
`--autotune-current-threshold`	Automatically find optimal current threshold (default). Use `--no-autotune-current-threshold` to disable.
`--validate-cycles`	Print detailed cycle validation diagnostics.
`--strict-time-resets`	Treat time resets within a cycle as fatal errors instead of warnings.

5. Plot Controls¶

Flag	Description
`--energy`	Generate specific energy (Wh/kg) vs. cycle plots.
`--derivative [CYCLES...]`	Generate dQ/dV (differential capacity) plots. If no cycle numbers follow, plots the last cycle. Example: `--derivative 1 50`.

6. Averaging¶

See the Averaging Guide for grouping logic and examples.

Flag	Description
`--average`, `--avg`	Average capacity metrics across replicate cells.
`--average-energy`, `--avg-energy`	Average energy metrics across replicate cells.
`--average-ignore-plan`	Average cells by filename only, ignoring step plan differences. Auto-enables `--average` if neither `--average` nor `--average-energy` is set.

7. Advanced & Debugging¶

Flag	Description
`--force-process`	Process files even if they appear incomplete or are flagged as "bad cells".
`--mapping-file <FILE>`	YAML or JSON file for custom column mappings (overrides built-in defaults).
`--heuristic-map`	Use fuzzy column name matching (default). Use `--no-heuristic-map` to disable.
`--debug`	Enable verbose debug logging to the console.
`--debug-step-plan`	Print the extracted step plan table. Uses `tabulate` for pretty-printing when installed; otherwise falls back to a plain DataFrame string with a warning.
`--debug-signatures`	Show unique step plan signatures for each file.

Exit Codes¶

BatteryProc uses structured exit codes for shell scripting and CI:

Code	Meaning
`0`	Success (all files processed, or at least one file succeeded in batch mode).
`1`	Unexpected error.
`2`	Parse error (file format invalid or unrecognized).
`3`	Data quality failure ("bad cell" detected).
`4`	Wrong data type (file does not contain battery cycling data).
`13`	Permission denied.

Note

In batch mode, the exit code is 0 as long as at least one file succeeded. Check console output for individual file failures.