ROOT CLI Reference

root-cli is a token-efficient command-line interface for analyzing CERN ROOT files. It provides significant token savings compared to the MCP JSON protocol by using human-readable commands and output instead of verbose JSON structures.

Quick Start

Set your data path once:

export ROOT_MCP_DATA_PATH=/path/to/your/data

Or specify per command:

root-cli -d /path/to/data <command>

All commands support --json flag for machine-readable output.

Command Overview

File Operations

ls [pattern]

List ROOT files in the data directory.

-l, --limit

Maximum files to list (default: 100)

Example:

root-cli ls
root-cli ls "run_*.root" --limit 10
inspect <file.root>

Inspect ROOT file structure (TTrees and RNTuples, branches, histograms).

Example:

root-cli inspect /data/sample.root
branches <file.root> <tree>

List branches in a TTree or RNTuple with type information.

-p, --pattern

Glob pattern for branch names

-l, --limit

Maximum branches to list (default: 100)

-s, --stats

Compute statistics (slower)

Example:

root-cli branches /data/sample.root events
root-cli branches /data/sample.root events --pattern "muon_*"
validate <file.root>

Validate ROOT file integrity and readability.

Example:

root-cli validate /data/sample.root

Data Access

read <file.root> <tree> <branches...>

Read branch data from a TTree or RNTuple with optional selection.

-s, --selection

Cut expression (C++ syntax, e.g., "pt > 20 && abs(eta) < 2.4")

-l, --limit

Maximum entries to read

-o, --offset

Skip first N entries

--flatten

Flatten jagged arrays

-d, --defines

Derived variables (name=expr)

Example:

root-cli read /data/sample.root events met muon_pt
root-cli read /data/sample.root events met --selection "met > 50" --limit 1000
stats <file.root> <tree> <branches...>

Compute statistics (mean, std, min, max, median) for branches.

-s, --selection

Cut expression

Example:

root-cli stats /data/sample.root events met muon_pt jet1_pt
sample <file.root> <tree>

Get a sample from a TTree or RNTuple.

--size

Sample size (default: 100)

--method

Sampling method: first or random

--seed

Random seed (for random sampling)

Example:

root-cli sample /data/sample.root events --size 50 --method random
export <file.root> <tree> <branches...> -o <output>

Export branch data to CSV, JSON, or Parquet.

--format

Output format: csv, json, or parquet (default: csv)

-s, --selection

Cut expression

-l, --limit

Maximum entries to export

Example:

root-cli export /data/sample.root events met pt -o data.csv
root-cli export /data/sample.root events met -o data.parquet --format parquet

Histogram Analysis

histogram <file.root> <tree> <branch>

Create 1D histogram with optional fit.

-b, --bins

Number of bins (default: 100)

-r, --range MIN MAX

Histogram range

-s, --selection

Cut expression

-f, --fit

Fit model: gaussian, exponential, polynomial, crystal_ball

--fit-range MIN MAX

Fit range

Example:

root-cli histogram /data/sample.root events met --bins 50
root-cli histogram /data/sample.root events dimuon_mass --fit gaussian --fit-range 80 100
histogram2d <file.root> <tree> <x_branch> <y_branch>

Create 2D histogram for correlation studies.

--xbins

Number of X bins (default: 50)

--ybins

Number of Y bins (default: 50)

--xrange

X axis range

--yrange

Y axis range

Example:

root-cli histogram2d /data/sample.root events met met_phi
fit <histogram.json> <model>

Fit a mathematical model to histogram data.

--fit-range MIN MAX

Fit range

-i, --initial-params

Initial parameters (name=value)

Example:

root-cli fit /tmp/root_mcp/met_hist.json gaussian
hist-arithmetic <operation> <hist1.json> <hist2.json>

Perform bin-by-bin histogram arithmetic.

Operations: add, subtract, multiply, divide, asymmetry

Example:

root-cli hist-arithmetic divide /tmp/data.json /tmp/mc.json

Statistical Analysis

correlation <file.root> <tree> <branches...>

Compute correlation matrix between branches.

--method

Correlation method: pearson or spearman (default: pearson)

Example:

root-cli correlation /data/sample.root events met jet1_pt jet2_pt

Kinematics

invariant-mass <file.root> <tree>

Compute invariant mass from particle 4-vectors.

--pt

PT branches (can specify multiple: --pt mu1_pt --pt mu2_pt)

--eta

Eta branches

--phi

Phi branches

--mass

Mass branches (optional)

-s, --selection

Cut expression

-l, --limit

Maximum entries

Example:

root-cli invariant-mass /data/sample.root events \
  --pt mu1_pt mu2_pt \
  --eta mu1_eta mu2_eta \
  --phi mu1_phi mu2_phi

Visualization

plot1d <histogram.json> -o <output.png>

Create a 1D histogram plot.

-t, --title

Plot title

-x, --xlabel

X-axis label

-y, --ylabel

Y-axis label (default: Events)

--log-y

Logarithmic Y axis

--style

Plot style: default, publication, presentation

Example:

root-cli plot1d /tmp/root_mcp/met_hist.json -o met.png \
  --title "MET Distribution" --xlabel "MET (GeV)"
plot2d <histogram2d.json> -o <output.png>

Create a 2D histogram plot.

-t, --title

Plot title

--colormap

Matplotlib colormap (default: viridis)

--log-z

Logarithmic color scale

Example:

root-cli plot2d /tmp/root_mcp/corr_hist2d.json -o corr.png \
  --colormap inferno

Utility

info

Show CLI information and available commands.

--json

Output in JSON format

Example:

root-cli info
root-cli info --json

Common Workflows

Exploratory Analysis

# 1. List available files
root-cli ls

# 2. Inspect file structure
root-cli inspect /data/sample.root

# 3. Check available branches
root-cli branches /data/sample.root events --pattern "muon_*"

# 4. Get basic statistics
root-cli stats /data/sample.root events met muon_pt

Histogram with Fit

# 1. Create histogram with fit
root-cli histogram /data/sample.root events dimuon_mass \
  --bins 100 --range 80 100 --fit gaussian --fit-range 85 95

# 2. Create publication plot
root-cli plot1d /tmp/root_mcp/dimuon_mass_hist.json \
  -o dimuon_mass.png --title "Dimuon Mass" --style publication

Data Export

# 1. Read data with selection
root-cli read /data/sample.root events met muon_pt \
  --selection "met > 50 && muon_pt > 20"

# 2. Export to Parquet
root-cli export /data/sample.root events met muon_pt \
  -o selected.parquet --format parquet --selection "met > 50"

Token Efficiency

The CLI provides significant token savings compared to MCP JSON protocol by using human-readable commands and output instead of verbose JSON structures.

For a typical analysis session, this translates to thousands of tokens saved.

See Also