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.
Output contract (agents and scripts)
Every command follows one contract, so an AI agent or a shell script can call any of them the same way.
| Rule | Behavior |
|---|---|
--json |
Every command except quickstart accepts it. stdout then holds exactly one JSON object. --help and --version still print plain text |
| stdout | Results only. Banners, progress and errors go to stderr |
| Errors | With --json, one JSON object on stderr: error, message, exit_code, and often hint. This includes argparse usage errors such as an unknown flag |
| Demos | demo <name> --json captures the printed walkthrough as output text inside the result |
| stdin | Pass - instead of a CSV path to read the CSV from stdin |
| Prompts | None when stdin is not a terminal. quickstart prints the workflow list; install-skills asks for --yes |
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Input or validation failure: missing file, unreadable CSV, failed contract |
| 2 | Usage error: bad flag, unknown name, workflow could not be detected |
| 3 | Unexpected internal error (please report it) |
A failed validation with --json is still a result: stdout carries
{"ok": false, "issues": [...]} and the exit code is 1.
cranalytics check loans.csv --json
cranalytics check --show-schema vintage --json
cat curves.csv | cranalytics vintage run - --no-cv --json
cranalytics install-skills --list --json
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 when
no role flags are supplied. ML modeling and survival also accept the roles and
configuration used by their run commands, so the selected roles can be
checked before execution.
| 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 |
Segmentation | Requires only fico_score, matching segment_fico(). Other columns pass through. Never auto-detected by bare cranalytics check. |
| 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 COL --target-col COL --split-col COL] |
Feature analytics without role flags; selected modeling roles with them | Role checks cover selected features, binary target, temporal split coverage, model family, window type, and fold count. |
| Survival | cranalytics survival check data.csv [--start-date-col COL --end-date-col COL --status-col COL --default-status STATUS] |
Portfolio without role flags; selected event inputs with them | Role checks cover dates, censoring cutoff, event mappings, cohorts, covariates, and competing-risk codes. |
| 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 base contract before validating the
supplied file. A successful check without role flags is reported as
base-only; pass the flags used by the eventual run for role-checked. Role checks catch common
role and configuration mistakes; they mirror run but do not guarantee it succeeds.
JSON check results include compatible_workflows: workflow names whose base
input contracts pass for the supplied data. For example, FICO-only data lists
only segmentation, and vintage-curve data lists only vintage. A configured
ML or survival workflow is also included when its selected roles pass validation.
Other names indicate base-input compatibility; separate transition matrices,
model roles, and run options still need validation. Rollforward checks use their
normalized, alias-resolved input and report compatibility independently of the
readiness score. Failed contract-check results include an empty list.
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; when a file uses the contract names vintage_name and mob (as the quickstart template does), the error hint names the --vintage-col and --mob-col flags to pass. |
| 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 Rollforward(df).run(mode="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:
- Run
cranalytics rollforward check <input_csv>first - Review
schema_issues.csvand fix any critical issues - Run
cranalytics rollforward run <input_csv>on clean data - Review
committee_summary.mdandchampion_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
- Choose Your Path — narrative workflow triage
- Workflow Map — compact command/input/output matrix
- Input Data Contracts — column requirements for all input shapes