Using it from the command line¶

The spectro command is the no-AI-agent door: everything the catalogue offers, reachable from a terminal - for exploration, scripting and CI. It needs no Python code.

Commands at a glance¶

Command	What it does
`spectro info`	Catalogue summary (counts, version).
`spectro list`	List algorithms, optionally by `--category`.
`spectro categories`	List the non-empty categories.
`spectro describe <name>`	Full details of one algorithm.
`spectro source <name>`	Print the wrapper's source code (or just the GitHub link with `--url-only`) - for auditing.
`spectro presets`	List every recipe (preset) the install can see: bundled, `SPECTRO_PRESET_PATH`, installed collections.
`spectro preset show <name>`	A recipe's variables, steps, references and source.
`spectro preset validate <file-or-name>...`	Check recipes without running them (format, algorithms, parameters, variables, kernel range).
`spectro run <algorithm>`	Run a single algorithm.
`spectro pipeline <preset>`	Run a whole recipe, with `--profile file.yaml` and `--set name=value` for its variables.

Add --json to any command for machine-readable output (handy in scripts and CI).

The CLI reference lists every command with its options and defaults; it is generated from the argument parser, so it is exactly what spectro --help says.

Discovering the catalogue¶

spectro info
spectro list --category line_fitting
spectro describe fit_gaussian_line
spectro source fit_gaussian_line --url-only   # GitHub permalink
spectro source fit_gaussian_line               # full wrapper source

describe shows the parameters, the required ones, the context inputs/outputs, the backend and the literature references:

fit_gaussian_line  v1.1.0  [line_fitting]

  Fit a single Gaussian (plus a linear continuum) to one spectral line.

  Backend: scipy
  References:
    - scipy.optimize.curve_fit - Levenberg-Marquardt / Trust Region Reflective

  Parameters:
    line_center_angstrom = None (required)
        Approximate line centre in Å (required).
    window_angstrom = 20.0
        Half-width of the fit window on each side of the line (Å).
    ...

Running one algorithm¶

# Load a spectrum and run an algorithm on it:
spectro run snr_der --input obs.fits

# Pass parameters with -p key=value (repeatable); values are auto-typed:
spectro run normalize_polynomial -i obs.fits -p order=3 -p sigma_clip=3.0

# Save the resulting spectrum (format chosen by extension):
spectro run normalize_polynomial -i obs.fits -o normalised.fits

The --input file is read into the context before the algorithm runs (FITS, ASCII or VOTable, by extension or URL). The exit code is 0 on success, non-zero on failure - so spectro run composes cleanly in shell scripts.

Running a recipe (preset)¶

spectro presets                                   # what is available, and from where
spectro preset show snr_check                     # variables and steps
spectro pipeline balmer_quick --input obs.fits
spectro pipeline snr_check --input obs.fits --json

A recipe that declares variables takes them from a profile file, from --set, or both (--set wins):

spectro pipeline be_halpha_ew --input obs.fits --profile alpy600_toulouse.yaml
spectro pipeline be_halpha_ew --input obs.fits --profile alpy600_toulouse.yaml --set half_width=8

You can also point pipeline at a YAML file directly, and check a file before sharing it:

spectro pipeline ./my_recipe.yaml --input obs.fits
spectro preset validate ./my_recipe.yaml --profile my_setup.yaml

See Recipes for the recipe / profile idea.

Scripting example¶

#!/usr/bin/env bash
# Batch SNR check over a directory of spectra.
for f in data/*.fits; do
  snr=$(spectro run snr_der --input "$f" --json | python -c \
        'import sys,json; print(json.load(sys.stdin)["context"]["metrics"]["snr_der"])')
  printf '%-30s SNR = %.0f\n' "$f" "$snr"
done

Same catalogue, every door¶

Whatever you do here, an AI agent can do through the MCP server, and your Python code can do through the library. The three are guaranteed to stay in sync because they are all thin layers over the same registry.