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 core workflows plus advanced and supporting paths interactively.

cranalytics quickstart [--workflow SLUG] [--show-requirements] [--write-template]

With no options, opens the interactive menu. 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.

Argument / option Default Description
--workflow SLUG (interactive menu) Run one workflow directly by registry slug. Examples: vintage, lifetime-loss, segmentation, feature-analytics, ml-modeling, survival, simulation, rollforward.
--show-requirements off Print data requirements without prompting for menu input. Combine with --workflow to show one workflow only.
--write-template off Write starter CSV template files. Combine with --workflow vintage, --workflow lifetime-loss, --workflow segmentation, --workflow feature-analytics, or --workflow rollforward to write only that workflow's template. Workflows without a template (for example ml-modeling) print a graceful "no starter template" message.

Examples:

# Run one guided workflow without the menu
cranalytics quickstart --workflow vintage

# Show one workflow's required columns
cranalytics quickstart --workflow lifetime-loss --show-requirements

# Write all starter CSV templates
cranalytics quickstart --write-template

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.

Stable demo names:

Demo name Workflow
vintage Vintage Curve Fitting
lifetime-loss Lifetime Loss Forecasting
segmentation FICO Segmentation
feature-analytics Feature Analytics
ml-modeling ML Modeling
survival Survival Analysis
simulation Portfolio Simulation
rollforward Rollforward Workflow

Prefer cranalytics demo <name> in docs, notebooks, and onboarding materials. The underlying example modules are implementation details.

check

Auto-detects and validates one supported base data-shape contract.

cranalytics check <file>
cranalytics check --show-schema [<workflow>]

Use this bare form only when the columns identify a single base contract. A single match is validated automatically; an ambiguous or absent match exits with code 2 and lists the candidates. --show-schema prints a workflow's required columns (default portfolio).

Exit codes: 0 validation passed; 1 validation failed, file not found, or unreadable; 2 usage error or auto-detection could not resolve a single workflow.

Argument / Option Description
file Path to a CSV file to auto-detect and validate. Optional if --show-schema is used alone.
--show-schema [workflow] Print the required columns for a workflow (default portfolio), then exit. No file required.

Example:

# Show expected schema for the default (portfolio) workflow
cranalytics check --show-schema

# Show expected schema for a specific workflow
cranalytics check --show-schema vintage

# Validate a file — auto-detect workflow from columns
cranalytics check my_portfolio.csv

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

Workflow checks

Every quickstart workflow has a check command:

cranalytics <slug> check <file> [--show-schema]

These commands validate the closest existing base data-shape contract, not every option required by the full workflow. This preserves the meaning of the Python cranalytics.check() front door while keeping runtime configuration explicit.

CLI workflow Command Contract checked Important gap
Vintage cranalytics vintage check data.csv Vintage Validates long-format curve input, not fitting choices.
Lifetime loss cranalytics lifetime-loss check data.csv Portfolio Does not validate the separate transition matrix or transition-history input.
Segmentation cranalytics segmentation check data.csv Portfolio segment_fico() can operate with only fico_score; this CLI preflight deliberately requires the broader portfolio shape.
Feature analytics cranalytics feature-analytics check data.csv Feature analytics Validates the modeling-frame shape, not a particular analysis choice.
ML modeling cranalytics ml-modeling check data.csv Feature analytics Does not choose a target, split column, feature set, or model family. The bundled example uses fpf30_flag and origination_quarter, but those are not universal defaults.
Survival cranalytics survival check data.csv Portfolio Validates the shared snapshot base shape only. It does not validate start/end date columns, status/default mappings, cohorts, or covariates required by survival.run().
Simulation cranalytics simulation check data.csv Portfolio Does not validate the separate transition matrix or simulation assumptions.
Rollforward cranalytics rollforward check data.csv Readiness report Deliberate exception: produces a scored readiness report, not plain Pandera contract validation.

--show-schema prints the underlying contract before validating the supplied file. For example, cranalytics ml-modeling check data.csv --show-schema prints the feature-analytics modeling-frame requirements and then validates the file.

The old positional form, cranalytics check <workflow> <file>, is removed. Use the workflow-first form above instead.

Workflow runs

Only workflows with an existing end-to-end Python boundary expose run:

cranalytics vintage run <file> [options]
cranalytics survival run <file> [options]
cranalytics ml-modeling run <file> [options]
cranalytics rollforward run <file> [options]

feature-analytics, lifetime-loss, segmentation, and simulation do not have a run(df) boundary, so they intentionally do not expose a CLI run verb. Use their focused Python APIs after check instead.

Workflow Required configuration Default / output Explicit limitation
Vintage None for standard vintage_date, months_on_book, and cumulative_loss_rate columns. Use --vintage-col, --mob-col, and --loss-col for another schema. Runs the built-in smoother comparison and prints its ranking. No artifacts are written because vintage.run() returns an in-memory session result. Input aliases accepted by check are not silently remapped by run.
Survival --start-date-col, --end-date-col, --status-col, and one or more --default-status STATUS. Fits Kaplan-Meier and prints the survival table. --covariate, --group-col, and --competing-status STATUS=CODE opt into additional analyses. The CLI cannot infer an event date or which status values are defaults; those choices are portfolio policy, not column-name conventions. No artifacts are written.
ML modeling Repeat --feature COLUMN, plus --target-col and --split-col. Binary --model-family logistic is the default and the temporal backtest summary is printed. Target, temporal split, and feature selection are modeling decisions. The example's fpf30_flag and origination_quarter are not safe universal defaults. No artifacts are written.
Rollforward None beyond the monthly rollforward input; migrated workflow flags remain available. Writes the workflow artifact directory; --output-dir defaults to ./rollforward_workflow_output. This command calls run_rollforward_workflow(...), not the in-memory rollforward.run(...), because the latter is model mode and cannot produce the legacy workflow artifacts.

Examples:

# Standard vintage input (override column names if your CSV differs)
cranalytics vintage run vintage.csv

# Survival event policy must be explicit
cranalytics survival run loans.csv \
  --start-date-col origination_date \
  --end-date-col event_date \
  --status-col loan_status \
  --default-status ChargedOff

# Modeling roles must be explicit; logistic is the safe baseline default
cranalytics ml-modeling run modeling.csv \
  --feature fico_score --feature dti \
  --target-col default_flag --split-col origination_quarter

rollforward

Use check for readiness and run for the artifact-producing monthly workflow. The old bare rollforward form is removed.

cranalytics rollforward check <input_csv> [options]
cranalytics rollforward run <input_csv> [options]
Argument / Option Default Description
check <input_csv> (required for readiness) Run the data-readiness diagnostic report. Columns are alias-resolved automatically.
run <input_csv> (required for workflow) Run the canonical monthly workflow and write its artifacts.
--output-dir PATH command-specific Defaults to ./rollforward_readiness_output for check or ./rollforward_workflow_output for run.
--holdout-months N 6 Months to hold out for validation or readiness checks.
--min-train-months N command-specific Defaults to 6 for readiness and 12 for run.
--step-months N 1 Step size between rolling cutoffs. Used by run only.
--segment ID (all) Restrict work to a single segment ID.
--amtloan-col NAME amtloan Column name for original origination balance.
--strict off Fail on data quality issues instead of writing diagnostics only.

Readiness outputs (check): - schema_issues.csv — Data quality issues with severity and issue codes - readiness_summary.json — Pass/fail assessment, segment coverage, and shared operational_status - rollforward_run_summary.json — Shared rollforward summary with surface, status, and operational_status - workflow_run_metadata.json — Lightweight governance metadata with shared operational_status and JSON-safe run summary

Workflow outputs (run):

File Description
schema_issues.csv Data contract issues
normalized_rollforward_data.csv Cleaned, alias-resolved rollforward data
rollforward_run_summary.json Shared rollforward summary with surface, status, and operational_status
workflow_run_metadata.json Lightweight governance metadata with shared operational_status and run summary
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 plus shared operational_status
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, including shared operational_status
forecast_vs_actual.png Forecast accuracy plot
model_lift.png Champion vs challenger lift chart
segment_concentration.png Balance concentration by segment

Examples:

# Readiness first
cranalytics rollforward check rollforward.csv \
  --output-dir ./diag \
  --holdout-months 3

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

Legacy split-command aliases were removed in 0.2.0.

Typical workflow:

  1. Run cranalytics rollforward check <input_csv> first
  2. Review schema_issues.csv and fix any critical issues
  3. Run cranalytics rollforward run <input_csv> 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, predictive-credit-modeling) 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.
--list off List bundled skill names and exit. Read-only — installs nothing.
--describe [NAME] off Print bundled skill descriptions and exit. Pass a skill name to describe just one. Read-only — installs nothing.

Install targets (checked in order): 1. CLAUDE_SKILLS_DIR (if set and points to an existing directory) 2. ~/.claude/skills/ (Claude Code primary) 3. ~/.agents/skills/ (secondary) 4. ~/.config/claude/skills/

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

# Discover what's bundled without installing
cranalytics install-skills --list
cranalytics install-skills --describe
cranalytics install-skills --describe vintage-loss-curves

See also