fasthep-cli

fasthep-cli provides the unified command-line interface for the FAST-HEP ecosystem.

It exposes workflow, rendering, inspection, and utility commands through the fasthep executable.

Scope

fasthep-cli is responsible for:

• the fasthep command
• workflow compilation and execution commands
• environment and package inspection
• dataset/example downloads
• CLI formatting and UX
• command dispatch to FAST-HEP packages

It intentionally contains very little domain logic itself.

Design philosophy

fasthep-cli should remain thin.

The CLI should:

• parse arguments
• call public package APIs
• display results

It should not:

• implement workflow internals
• duplicate runtime logic
• bypass public APIs

This keeps:

• notebook APIs
• Python APIs
• CLI behavior

consistent across the ecosystem.

Relationship to other FAST-HEP packages

fasthep-cli primarily dispatches to:

• fasthep-flow

  • workflow compilation and execution

• fasthep-curator

  • dataset inspection and validation

• fasthep-render

  • plotting and reporting

• fasthep-carpenter

  • HEP analysis transforms and runtime extensions

• fasthep-toolbench

  • shared CLI utilities and helpers

Installation

Install directly:

pip install fasthep-cli

Or install the meta package:

pip install fasthep

Development environment:

pixi install
pixi run ci

Example commands

Scaffold project-local profiles:

fasthep init --include fasthep_workshop:registry
fasthep init --include ./profiles/custom.yaml

Compile a workflow:

fasthep compile examples/CMS/Hinv/workflow.yaml --work-dir build/Hinv

Run a compiled plan:

fasthep run-plan build/Hinv/plan.yaml

Compile and run in one step:

fasthep run examples/CMS/Hinv/workflow.yaml --work-dir build/Hinv

Inspect installed FAST-HEP packages:

fasthep versions

Inspect a ROOT TTree schema:

fasthep inspect schema input.root --tree Events

Extract pasteable field lists or starter alignment schemas:

fasthep inspect schema input.root \
  --tree Events \
  --include 'GenJet*' \
  --include 'GenMET*' \
  --format yaml-list

fasthep inspect schema input.root \
  --tree Events \
  --include 'GenJetAK8_*' \
  --format alignment

Download workshop/example datasets:

fasthep download --json examples/downloads.json --destination data

Documentation

Main FAST-HEP documentation:

• https://fast-hep.github.io

API documentation for this package:

• https://fasthep-cli.readthedocs.io/en/latest/

Repository

Main FAST-HEP repository and project links:

• https://github.com/FAST-HEP/fasthep

Contributing

Contribution guidelines, development setup, and project-wide documentation are maintained centrally in the main FAST-HEP repository.

Legacy branch

The pre-split prototype CLI implementation is preserved in legacy repositories and branches.

The current repository contains the split-package CLI architecture.

Status

FAST-HEP is currently in active pre-alpha development.

Interfaces and commands may evolve rapidly while the ecosystem stabilizes.