Skip to content

CLI Reference

All cranalytics commands follow the pattern:

cranalytics <subcommand> [arguments] [options]

Run cranalytics --help or cranalytics <subcommand> --help for inline help at any time.

Canonical first command

For a first-time user, the recommended first command is:

cranalytics quickstart

Use the other subcommands once you know which workflow or data shape you want.

cranalytics --version

Print the installed package version and exit.

cranalytics --version
# cranalytics 0.x.y

quickstart

Guided introduction that walks through the five core workflows interactively.

cranalytics quickstart

No arguments or options. Prints a structured overview of available workflows, their expected input shapes, the first win to look for in each path, and the recommended next step after you pick a workflow.

If you are new to the package, start here before using demo.

demo

Run a packaged demo script or list all available demos.

cranalytics demo [name]
cranalytics demo --list
Argument / Option Description
name Demo name to run. One of the names shown by --list, or all to run every demo in sequence. Optional.
--list Print the names of all available demos and exit.

Example:

cranalytics demo --list
cranalytics demo vintage
cranalytics demo all

--list prints the stable demo names together with the human-friendly workflow title so the command surface matches the package docs.

Equivalent to running the demo scripts directly:

python -m cranalytics.examples.core_vintage

validate-data

Validate a CSV file against the portfolio schema. Useful for checking column names, types, and value ranges before running a loss forecasting workflow.

cranalytics validate-data <file> [--show-schema]
Argument / Option Description
file Path to a CSV file to validate. Optional if --show-schema is used alone.
--show-schema Print the expected column names and accepted status values, then exit. No file required.

Validates against: PortfolioSchema — see Input Data Contracts — Portfolio.

Example:

# Show expected schema without a file
cranalytics validate-data --show-schema

# Validate a file
cranalytics validate-data my_portfolio.csv

Output: Prints either a success message or a list of validation failures with column names and constraint descriptions.

Note: Currently validates portfolio data only. To validate rollforward, vintage, or wide CGCO data programmatically, use the Python validation helpers:

from cranalytics.validation import validate_flow_input, validate_vintage, validate_wide_vintage

rollforward-readiness

Run pre-flight data quality checks on a rollforward CSV and write a readiness report. Use this before rollforward-workflow to understand data quality issues and whether your data has sufficient history for modeling.

cranalytics rollforward-readiness <input_csv> [options]
Argument / Option Default Description
input_csv (required) Path to input rollforward CSV file. Columns are alias-resolved automatically — see Rollforward aliases.
--output-dir PATH ./rollforward_readiness_output Directory to write report artifacts. Created if it does not exist.
--holdout-months N 6 Months to hold out for validation checks.
--min-train-months N 6 Minimum months of training history required per segment to be included.
--segment ID (all) Restrict report to a single segment ID.
--amtloan-col NAME amtloan Column name for original origination balance. Used to compute CGCO%. Falls back to first observed outstanding_balance if not found.
--strict off Exit with a non-zero code on any critical data issue instead of writing a diagnostics-only report.

Output files written to --output-dir: - schema_issues.csv — Data quality issues with severity and issue codes - readiness_summary.json — Pass/fail assessment and segment coverage

Example:

cranalytics rollforward-readiness rollforward.csv --output-dir ./diag --holdout-months 3

Legacy CLI alias remains supported.

rollforward-workflow

Run the full end-to-end monthly Rollforward workflow: data validation, hazard curve fitting, backtesting, champion/challenger selection, forecasting, and KPI reporting. Writes all artifacts to disk.

cranalytics rollforward-workflow <input_csv> [options]
Argument / Option Default Description
input_csv (required) Path to input rollforward CSV file. Columns are alias-resolved automatically.
--output-dir PATH ./rollforward_workflow_output Directory to write all output artifacts.
--holdout-months N 6 Months to hold out for backtest validation.
--min-train-months N 12 Minimum months of training history required per segment. Segments below this threshold are excluded.
--step-months N 1 Step size (in months) between rolling backtest cutoffs. Increase to speed up backtesting on large datasets.
--segment ID (all) Restrict workflow to a single segment ID.
--amtloan-col NAME amtloan Column name for original origination balance.
--strict off Fail on critical data issues instead of writing a diagnostics-only report.

Output files written to --output-dir:

File Description
schema_issues.csv Data contract issues
normalized_rollforward_data.csv Cleaned, alias-resolved rollforward data
backtest_results.csv Per-variant, per-cutoff backtest metrics
variant_summary.csv Summary statistics per variant (mean MAPE, success rate)
champion_selection.json Selected champion and challengers with promotion reason
forecast_vs_actual.csv Holdout validation: forecasted vs actual flows
segment_kpis.csv Per-segment balance, charge-off rate, hazard rates
portfolio_kpis.json Portfolio-level KPIs (total balance, total charge-offs, n_segments)
committee_summary.md Human-readable narrative summary for risk committee review
forecast_vs_actual.png Forecast accuracy plot
model_lift.png Champion vs challenger lift chart
segment_concentration.png Balance concentration by segment

Example:

cranalytics rollforward-workflow rollforward.csv \
  --output-dir ./rollforward_out \
  --holdout-months 6 \
  --min-train-months 12

Legacy CLI alias remains supported.

Typical workflow:

  1. Run rollforward-readiness first to check data quality
  2. Review schema_issues.csv and fix any critical issues
  3. Run rollforward-workflow on clean data
  4. Review committee_summary.md and champion_selection.json

install-skills

Install the bundled Claude skills (vintage-loss-curves, loss-forecasting, portfolio-diagnostics) to a local skills directory for use with Claude Code.

cranalytics install-skills [options]
Option Default Description
--dry-run off Show planned actions without writing any files.
--yes off Create the default skills directory without prompting for confirmation.
--skill NAME (all) Install only the named skill. Repeatable: --skill vintage-loss-curves --skill loss-forecasting.
--conflict {overwrite,skip} overwrite What to do when a skill already exists at the destination.
--version off Print the package and skills bundle version, then exit.

Install targets (checked in order): 1. ~/.claude/skills/ (Claude Code primary) 2. ~/.agents/skills/ (secondary)

Example:

# Dry run to preview
cranalytics install-skills --dry-run

# Install all skills
cranalytics install-skills --yes

# Install a single skill, skip if already present
cranalytics install-skills --skill vintage-loss-curves --conflict skip

See also