Proposal: machine-friendly CLI based on #302

[day01]

Summary

PR #302 already explores a CLI example for sampling and density evaluation. It supports normal, binomial, and multinomial distributions and was partly motivated by easier verification using external programs.

I would like to propose developing this idea into a separate, machine-friendly statrs-cli project.

Motivation

Using statrs currently requires writing and compiling a Rust program. This is appropriate for applications, but inconvenient for one-off calculations, shell scripts, implementation verification, and automated tools.

A CLI could make common operations directly accessible:

statrs distribution normal cdf --mean 0 --std-dev 1 --x 1.96
statrs sample normal --mean 0 --std-dev 1 --count 100 --seed 42
statrs test t-one-sample --population-mean 200 --input values.json
statrs describe --input values.json

This would also be useful for AI coding agents.

Models can generate Python, Rust, or R code for statistical calculations, but this requires:

• selecting and installing dependencies,
• generating correct code against the selected library version,
• executing temporary programs,
• handling runtime and validation errors,
• parsing potentially inconsistent output.

A stable CLI would provide a smaller, explicit, and reproducible interface.

Models are generally better suited to selecting an operation and interpreting its result than performing numerical calculations themselves. With a CLI, an agent could select the appropriate distribution or statistical test, invoke statrs-cli, and then explain the structured result.

This could reduce numerical hallucinations and remove the need to generate calculation code for supported operations.

Machine-friendly interface

The CLI should be useful for both humans and automated callers.

Suggested properties:

• JSON input and output,
• support for stdin and stdout,
• documented non-zero exit codes,
• explicit and structured validation errors,
• deterministic sampling with an explicit seed,
• no interactive prompts,
• discoverable operations and parameters.

Example:

statrs distribution normal cdf \
    --mean 0 \
    --std-dev 1 \
    --x 1.96 \
    --output json

{
  "distribution": "normal",
  "operation": "cdf",
  "parameters": {
    "mean": 0.0,
    "std_dev": 1.0
  },
  "x": 1.96,
  "value": 0.9750021048517795
}

Capability discovery could be exposed through commands such as:

statrs schema
statrs schema distribution normal
statrs schema test mann-whitney-u

This would allow scripts and agents to inspect the interface supported by the installed version.

Separate repository

I suggest starting statrs-cli as a separate repository.

This would allow the command interface, dependencies, release cycle, and output schema to evolve independently without affecting the core statrs crate.

Open discussion :)