Skip to content

CLI

PhronesisML provides a Typer-based CLI that wraps the SDK. Run the full ML pipeline from the command line.

Info

Install the CLI extras first: pip install phronesisml[cli]

Commands

phronesisml ships 13 commands, all thin wrappers over the SDK:

Command Description
run Run the full Phronesis pipeline on a dataset
info Show Phronesis version and installed components
version Print the installed phronesisml version
capabilities Report SDK capabilities: tasks, engines, stages, APIs
doctor Run offline dependency and self checks
analyze Load, clean, validate, and profile a dataset
validate Load, clean, and validate a dataset
profile Profile a dataset (alias of analyze)
train Run the full ML pipeline and report the trained model
evaluate Run model selection and evaluation on a dataset
explain Explain model predictions using SHAP
report Generate a Markdown report of the full pipeline
compare Train several models on a dataset and rank them

The authoritative list is phronesisml --help.

phronesisml run

Run the full ML pipeline on a dataset:

phronesisml run data/customers.csv

Options:

Flag Short Description Default
--engine -e Force engine: pandas, polars, spark auto
--nulls -n Null strategy: drop, fill, flag drop
--verbose -v Enable debug logging off

Examples:

# Use Polars engine with fill strategy
phronesisml run data.csv --engine polars --nulls fill

# Verbose output
phronesisml run data.csv -v

# Combine options
phronesisml run data.csv -e polars -n flag -v

What it does:

  1. Loads the dataset
  2. Cleans nulls and encodes types
  3. Validates data quality
  4. Runs statistical analysis
  5. Detects the prediction target
  6. Engineers features
  7. Selects and trains the best model
  8. Evaluates performance
  9. Generates a Markdown report
  10. Saves artifacts to disk

phronesisml info

Show information about PhronesisML:

phronesisml info

Output:

Phronesis v0.3.0
Python 3.12.13 (main, Jun 11 2026, 04:05:29) [MSC v.1944 64 bit (AMD64)]
  Polars: 1.43.2
  Pandas: 2.3.3
  LangGraph: installed

phronesisml evaluate

Run cross-validated model selection and evaluation offline:

phronesisml evaluate data.csv

Options:

Flag Short Description Default
--engine -e Force engine: pandas, polars, spark auto
--nulls -n Null strategy: drop, fill, flag drop
--cv Cross-validation folds (>= 2) SDK default
--verbose -v Enable debug logging off

Output: best model type and score, resolved task type, evaluation metrics, and any ambiguity caveat.

phronesisml compare

Train several models on a dataset and rank them:

phronesisml compare data.csv            # default model set
phronesisml compare data.csv -m random_forest -m gradient_boosting

Options:

Flag Short Description Default
--model -m Model(s) to compare (repeatable) all candidates
--engine -e Force engine auto
--nulls -n Null strategy drop
--cv Cross-validation folds (>= 2) SDK default
--verbose -v Enable debug logging off

Examples

Basic Usage

# Run with defaults
phronesisml run data.csv

# Run with Polars
phronesisml run data.csv --engine polars

# Run with verbose logging
phronesisml run data.csv -v

Null Handling

# Drop rows with nulls (default)
phronesisml run data.csv --nulls drop

# Fill nulls with 0
phronesisml run data.csv --nulls fill

# Flag nulls as separate columns
phronesisml run data.csv --nulls flag

Engine Selection

# Force Pandas
phronesisml run data.csv --engine pandas

# Force Polars
phronesisml run data.csv --engine polars

# Force Spark (requires pyspark)
phronesisml run data.csv --engine spark

Exit Codes

Code Meaning
0 Success
1 Pipeline failed (check error output)
2 Invalid arguments

Output Format

The CLI outputs a Markdown report to stdout. Redirect it to a file:

phronesisml run data.csv > report.md

Or view it with a Markdown renderer:

phronesisml run data.csv | glow -

Verbose Mode

Enable debug logging with -v:

phronesisml run data.csv -v

Output includes:

  • File loading details
  • ETL transformations
  • Validation results
  • Target detection confidence
  • Feature engineering steps
  • Model selection process
  • Training progress
  • Evaluation metrics

Troubleshooting

phronesisml: command not found

pip install phronesisml[cli]

Legacy console / redirected output

The CLI reconfigures stdout/stderr to UTF-8 (with a backslashreplace fallback) at import time, so stage-graph glyphs render cleanly on Windows consoles, pipes, and redirects. If a wrapper still chokes on non-ASCII output, use the Python SDK instead:

from phronesisml import Phronesis
ml = Phronesis("data.csv")
ml.run()

Slow first run

The first run() call compiles the LangGraph graph (~0.5s overhead). Subsequent calls reuse the cached graph.