Command Reference

This page documents every command exposed by the current first-party Heliokit components. A value marked Required must be supplied on the command line. Optional values have the listed default. Paths may be absolute or relative; quote a path when it contains spaces.

The CLI checks argument types and enumerated choices before execution. File existence, dataset names, array shapes, and model assets are checked by the component at runtime.

Global option

--json may be placed before any Heliokit command, for example heliokit --json components list. It is optional, takes no value, and emits the command result as formatted JSON. It is particularly useful for automation.

Host commands

heliokit components list

Argument	Required	Format / default	Meaning
--kind	No	data, filter, tool, model, pipeline, viz3d, or viz2d	Limits the listing to one component group.

heliokit components install PACKAGE [PACKAGE ...]

Argument	Required	Format / default	Meaning
PACKAGE	Yes	One or more distribution names	For example heliokit-data-vti. Local mode resolves packages under cli/ first and falls back to the configured package index.
--online	No	Flag; off by default	Use the package index only; do not inspect local sources.
--cli-root	No	Repository root or its cli directory	Overrides the local package search root.
--dry-run	No	Flag; off by default	Prints the resolved installation plan without changing the environment.
-e, --editable	No	Flag; off by default	Uses an editable installation for locally resolved packages.

Data readers

The following commands use the same argument schema:

heliokit data read cdf INPUT [--script PATH] [--include-values]
heliokit data read fits INPUT [--script PATH] [--include-values]
heliokit data read h5 INPUT [--script PATH] [--include-values]
heliokit data read hdf INPUT [--script PATH] [--include-values]
heliokit data read nc INPUT [--script PATH] [--include-values]
heliokit data read plt INPUT [--script PATH] [--include-values]
heliokit data read swv INPUT [--script PATH] [--include-values]

fits also accepts the alias fts; h5 accepts hdf5; nc accepts netcdf; and swv accepts swb. The selected reader names the expected source format, although a custom script can replace the built-in reader.

Argument	Required	Format / default	Meaning
INPUT	Yes	Existing file path	Data file to read. Built-in support: CDF .cdf; FITS .fits/.fts; HDF5 .h5/.hdf5; HDF4 .hdf; NetCDF .nc; Tecplot .plt; SWV text .swv or SWB binary .swb.
--script	No	Existing Python file	Custom reader module. It must define main(input_path) and return the normal Heliokit data mapping.
--include-values	No	Flag; off by default	Includes array values in CLI output. Leave off for large datasets to return only the summary and metadata.

heliokit data read vti INPUT

Argument	Required	Format / default	Meaning
INPUT	Yes	Existing .vti file	VTK XML ImageData input.
--include-values	No	Flag; off by default	Includes point-data arrays rather than only array names, origin, spacing, dimensions, and bounds.

heliokit data write

heliokit data write --output OUTPUT (--source SOURCE | --json-input JSON) [--reader NAME]

Argument	Required	Format / default	Meaning
--output	Yes	Output path	.h5, .hdf, or .swb writes a native structured file. .json and .swv write JSON.
--source	Conditional	Existing structured data file	Source file to convert. Supply exactly one of --source and --json-input.
--json-input	Conditional	Existing JSON file	Input Heliokit data mapping. Supply exactly one of --source and --json-input.
--reader	No	Reader name	Overrides format inference for --source. Valid built-in names are fits, nc, plt, cdf, hdf, h5, and swv. VTI summary conversion is not supported.

heliokit data fetch ace

Argument	Required	Format / default	Meaning
--output	Yes	Output path	Destination for the recent ACE solar-wind dataset. The extension should match the requested format.
--format	No	csv, json, swv, swb, h5, or hdf; defaults to the output suffix	Output representation. Use a matching suffix such as .csv, .json, .swv, .swb, .h5, or .hdf.

Dataset selectors

Filters read arrays from a structured data file with selectors. A selector has the exact form PATH::DATASET. Both parts are required. Dataset names are case-sensitive and must exist in the referenced source file.

Scalar attributes use NAME=PATH::DATASET. Vector attributes use exactly three selectors: NAME=PATH::DATASET,PATH::DATASET,PATH::DATASET. Repeat an option to provide multiple attributes.

MAG_CHB filter

heliokit run filter mag_chb --rad SEL --theta SEL --phi SEL --a1 SEL --a2 SEL --a3 SEL \
  --chb-tindex INT --chb-findex INT --output PATH [--attribute-cs scs|ccs] \
  [--start-r FLOAT] [--des-r FLOAT] [--in-r FLOAT] [--out-r FLOAT]

mag-chb is an alias for mag_chb.

Argument	Required	Format / default	Meaning and constraints
--rad, --theta, --phi	Yes	Dataset selectors	Radius, polar angle, and azimuth arrays. All three position arrays must describe the same grid.
--a1, --a2, --a3	Yes	Dataset selectors	Vector components. Use BR/BT/BF with scs or BX/BY/BZ with ccs; their shape must match the position grid.
--attribute-cs	No	scs (default) or ccs	Coordinate system used by the three attribute arrays.
--in-r, --out-r	No	Floating-point radii; default to the rounded minimum and maximum of rad	Must satisfy in-r <= out-r and both values must be within the minimum and maximum of rad.
--start-r, --des-r	No	Floating-point radii; default to the rounded minimum and maximum of rad	Must satisfy start-r <= des-r and both must be inside [in-r, out-r].
--chb-tindex, --chb-findex	Yes	Integer indices	CHB grid indices. The desktop form accepts positive integers; choose indices valid for the supplied theta and phi grids.
--output	Yes	.h5, .hdf, or .swb path	Output containing pt_type and chb.

Mesh to VTI: spherical coordinates

heliokit run filter meshtovtk_scs --rad SEL --theta SEL --phi SEL \
  [--scalar NAME=SEL] [--vector-scs NAME=SEL,SEL,SEL] [--vector-ccs NAME=SEL,SEL,SEL] \
  --output OUTPUT [--active-scalar NAME] [--active-vector NAME] \
  [--radius-min FLOAT] [--radius-max FLOAT] [--size INT] [--emit-vtu]

mesh_to_vtk_scs is an alias for meshtovtk_scs.

Argument	Required	Format / default	Meaning and constraints
--rad, --theta, --phi	Yes	Dataset selectors	Spherical position arrays; their dimensions define the source mesh.
--scalar	Conditional	Repeatable NAME=SEL	Scalar attribute. At least one scalar or vector option is required.
--vector-scs	Conditional	Repeatable NAME=SEL,SEL,SEL	Spherical vector attribute with three components.
--vector-ccs	Conditional	Repeatable NAME=SEL,SEL,SEL	Cartesian vector attribute with three components.
--active-scalar, --active-vector	No	Attribute name	Name of one supplied scalar or vector to mark as active in VTK. When omitted, the first scalar and first vector attribute are selected, matching the desktop combo-box default.
--radius-min, --radius-max	No	Floating-point radius; default to the rounded RAD range	Optional cropped output range. Omit either value to use the corresponding desktop-style RAD range boundary.
--size	No	Integer; default 300	Uniform output sampling dimension, producing size x size x size samples. The desktop form restricts this to a positive integer.
--emit-vtu	No	Flag; off by default	Writes an additional VTU file beside the VTI output.
--output	Yes	.vti path	VTK XML ImageData destination.

Mesh to VTI: Cartesian coordinates

heliokit run filter meshtovtk_ccs [--scalar NAME=SEL] [--vector NAME=SEL,SEL,SEL] \
  --origin X,Y,Z --spacing DX,DY,DZ --dimensions NX,NY,NZ --output OUTPUT

mesh_to_vtk_ccs is an alias for meshtovtk_ccs.

Argument	Required	Format / default	Meaning and constraints
--scalar	Conditional	Repeatable NAME=SEL	Scalar attribute. At least one scalar or vector option is required.
--vector	Conditional	Repeatable NAME=SEL,SEL,SEL	Cartesian vector attribute with exactly three components.
--active-scalar, --active-vector	No	Attribute name	Name of one supplied scalar or vector to mark as active in VTK. When omitted, the first scalar and first vector attribute are selected.
--origin	Yes	X,Y,Z; three floats	Spatial origin of the Cartesian grid.
--spacing	Yes	DX,DY,DZ; three floats	Grid spacing on each axis.
--dimensions	Yes	NX,NY,NZ; three integers	Number of grid points on each axis. The desktop form uses positive integer values.
--output	Yes	.vti path	VTK XML ImageData destination.

Batch Mesh to VTI

heliokit run filter meshtovtk_scs_batch --manifest MANIFEST.json [--continue-on-error]
heliokit run filter meshtovtk_ccs_batch --manifest MANIFEST.json [--continue-on-error]

mesh_to_vtk_scs_batch and mesh_to_vtk_ccs_batch are aliases. The manifest may be either a JSON array or an object with an items array. Each item is a JSON object using the same keys as the matching single-run command, with hyphenated CLI options written as underscored JSON keys. For example, active_scalar, radius_min, and emit_vtu.

Argument	Required	Format / default	Meaning and constraints
--manifest	Yes	Existing JSON file	Batch item list. Each item must contain the required single-run fields such as rad, theta, phi, and output for SCS, or origin, spacing, dimensions, and output for CCS.
--continue-on-error	No	Flag; off by default	Records failed items and continues. Without this flag, the first item failure stops the batch.

Scatter to VTI

heliokit run filter scattertovtk --x SEL --y SEL --z SEL \
  [--scalar NAME=SEL] [--vector NAME=SEL,SEL,SEL] --output OUTPUT \
  [--active-scalar NAME] [--active-vector NAME] [--size INT] [--emit-vtu]

scatter_to_vtk is an alias for scattertovtk.

Argument	Required	Format / default	Meaning and constraints
--x, --y, --z	Yes	Dataset selectors	Cartesian point coordinates.
--scalar	Conditional	Repeatable NAME=SEL	Scalar attribute. At least one scalar or vector option is required.
--vector	Conditional	Repeatable NAME=SEL,SEL,SEL	Cartesian vector attribute with exactly three components.
--active-scalar, --active-vector	No	Attribute name	Name of one supplied scalar or vector to mark as active in VTK. When omitted, the first scalar and first vector attribute are selected.
--size	No	Integer; default 300	Uniform output sampling dimension. The desktop form restricts this to a positive integer.
--emit-vtu	No	Flag; off by default	Writes an additional VTU file beside the VTI output.
--output	Yes	.vti path	VTK XML ImageData destination.

Format conversion

heliokit run filter format_convert --input INPUT --output OUTPUT

format-convert is an alias for format_convert. Supported input formats match the data readers: .hdf, .h5, .swb, .plt, .fits, .fts, .cdf, and .nc. Writable outputs are .h5, .hdf, and .swb; JSON/SWV output is available through heliokit data write.

Data calculator

heliokit run filter data_calculator --expression EXPR --var NAME=SEL \
  --output OUTPUT [--name DATASET] [--title TITLE]

data-calculator is an alias for data_calculator. Expressions run in a restricted NumPy namespace that includes common functions such as sqrt, sin, cos, where, maximum, and minimum. Input variables are loaded with --var and referenced by name inside the expression.

Argument	Required	Format / default	Meaning and constraints
--expression	Yes	NumPy-style expression	Formula evaluated over the named arrays, for example sqrt(bx**2 + by**2).
--var	Yes	Repeatable NAME=SEL	Input arrays available to the expression.
--name	No	Dataset name; default result	Output dataset name.
--title	No	Text; defaults to output filename stem	Output file title.
--output	Yes	.h5, .hdf, or .swb path	Output data file.

DST and Kp models

Both commands use the same argument schema:

heliokit run model dst [OPTIONS]
heliokit run model kp [OPTIONS]

Argument	Required	Format / default	Meaning and constraints
--mode	No	predict (default) or train	Selects inference or model training.
--advance-hours	No	Integer; default 6	Forecast lead time in hours. It must match the available weights and scaler layout for prediction.
--time-windows	No	Integer; default 72	Number of historical time steps in each model sequence. It must match the trained model input shape.
--model-dir	No	Existing directory	Model weights directory. When omitted, the controlled runtime’s default model location is used.
--results-dir	No	Directory path	Output directory for prediction or training artifacts. It is created as needed.
--epochs	No	Integer; default 1	Number of training epochs; used only by --mode train.
--train-file	Conditional	Existing CSV file	Required in train mode. The data layout must match the selected model’s training loader.
--uncertainty-iterations	No	Integer; default 10	Monte Carlo iterations for prediction uncertainty. Larger values increase runtime; it is used during prediction.

Prediction obtains recent ACE data from its configured upstream services. It requires compatible trained weights and scaler files in --model-dir (or the default controlled-environment location).

Geomagnetic pipeline

heliokit run pipeline geomag --output OUTPUT [--advance-hours INT] \
  [--time-windows INT] [--dst-model-dir PATH] [--kp-model-dir PATH]

Argument	Required	Format / default	Meaning
--output	Yes	.json path	Combined DST and Kp result summary. Its parent directory is created if needed.
--advance-hours	No	Integer; default 6	Forecast lead time forwarded to both model runs.
--time-windows	No	Integer; default 72	Sequence window forwarded to both model runs.
--dst-model-dir	No	Existing directory	Overrides the DST model asset location.
--kp-model-dir	No	Existing directory	Overrides the Kp model asset location.

ACWE coronal-hole detection

heliokit run tool acwe --output-dir DIRECTORY (--input-file FITS | \
  --time TIMESTAMP --email ADDRESS --download-dir DIRECTORY) [OPTIONS]

Argument	Required	Format / default	Meaning and constraints
--output-dir	Yes	Directory path	Result directory. The command creates an HDF5 result and PNG preview.
--input-file	Conditional	Existing AIA 193 FITS file	Local source image. Use this or the three download arguments below.
--time	Conditional	ISO 8601 local/UTC timestamp, for example 2026-07-09T00:00	JSOC acquisition time. Required when --input-file is omitted.
--email	Conditional	Email address	JSOC contact address; required with --time.
--download-dir	Conditional	Directory path	JSOC download destination; required with --time.
--resize-param	No	Float; default 8.0	Image downsampling factor. The desktop form accepts positive values.
--alpha	No	Float; default 0.3	Initial quiet-Sun threshold multiplier. The desktop form accepts positive values.
--foreground-weight	No	Float; default 1.0	ACWE foreground weight. The desktop form accepts positive values.
--background-weight	No	Float; default 0.02	ACWE background weight. The desktop form accepts positive values.
--narrowband	No	Float; default 2.0	ACWE narrowband width. The desktop form accepts positive values.

Use exactly one input route: --input-file or the complete --time / --email / --download-dir group. The downloaded image is fixed to the AIA 193 Angstrom wavelength used by the desktop workflow.

Data download tools

heliokit run tool aia --output-dir DIRECTORY --start-time TIME --end-time TIME --email ADDRESS [--wave INT]
heliokit run tool hmi --output-dir DIRECTORY --start-time TIME --end-time TIME --email ADDRESS
heliokit run tool eit --output-dir DIRECTORY --start-time TIME --end-time TIME [--wave INT]
heliokit run tool gong --output-dir DIRECTORY --start-time TIME --end-time TIME
heliokit run tool lasco --output-dir DIRECTORY --start-time TIME --end-time TIME [--detector C2|C3]
heliokit run tool secchi --output-dir DIRECTORY --start-time TIME --end-time TIME [--source STEREO_A|STEREO_B] [--detector DETECTOR] [--wave INT]
heliokit run tool wind --output-dir DIRECTORY --start-time DATE --end-time DATE

For AIA, EIT, GONG, HMI, LASCO, and SECCHI, --carrington-rotation INT may replace --start-time and --end-time. WIND requires an explicit start/end date range. --wave may be repeated.

Argument	Required	Format / default	Meaning and constraints
--output-dir	Yes	Directory path	Download destination. The directory is created if needed.
--start-time, --end-time	Conditional	ISO-like timestamp or date	Required unless --carrington-rotation is supplied. Examples: 2026-07-09T00:00 or 2026-07-09.
--carrington-rotation	Conditional	Integer	Alternative time selector for supported solar image instruments.
--wave	No	Repeatable integer Angstrom value	Validated against the instrument’s desktop wave list when one exists.
--source	No	Source string	Used by SECCHI; valid values are STEREO_A and STEREO_B. Other instruments use their fixed desktop source where applicable.
--detector	No	Detector string	Used by LASCO and SECCHI. Defaults to the first desktop detector option when omitted.
--email	Conditional	Email address	Required by JSOC-backed AIA and HMI exports.
--max-workers	No	Integer; default 8	Concurrent download workers.

Interactive visualization

The CLI visualization components below open native Matplotlib or VTK interactive windows and do not use the PyQt desktop shell. Use --save to write an image as well; --no-show suppresses the window when only an image file is needed.

heliokit run viz2d xy_line --input DATA [--x NAME] [--y NAME] [--save PNG] [--no-show]
heliokit run viz2d histogram --input DATA [--array NAME] [--bins INT] [--range MIN,MAX] [--save PNG] [--no-show]
heliokit run viz2d histogram2d --input DATA [--x NAME] [--y NAME] [--bins INT] [--save PNG] [--no-show]

2D defaults are inferred after loading the data file: xy_line uses a recognized X variable such as x or time when present, otherwise point index; Y defaults to the first other numeric variable. Histogram commands use the first numeric variable(s), finite data range, and 64 bins.

heliokit run viz3d volume --input DATA.vti [--array NAME] [--range MIN,MAX] [--save PNG] [--no-show]
heliokit run viz3d slice --input DATA.vti [--array NAME] [--axis x|y|z] [--index INT] [--save PNG] [--no-show]
heliokit run viz3d iso_surface --input DATA.vti [--array NAME] [--value FLOAT] [--save PNG] [--no-show]
heliokit run viz3d wireframe --input DATA.vti [--array NAME] [--save PNG] [--no-show]

3D defaults are inferred from VTK point data: the first scalar-compatible array is selected, scalar range uses finite min/max values, slice uses the middle slice on the selected axis, and iso_surface uses the middle of the scalar range. volume and slice currently require vtkImageData inputs such as .vti. wireframe can also display geometry without scalar arrays.

Registered P1 components without headless adapters

The following first-party components are installable and discoverable through heliokit components list. They expose a stable placeholder argument schema:

heliokit run KIND NAME [--input PATH] [--output PATH] [--config PATH] [--workspace PATH]

--input may be repeated. --output, --config, and --workspace are optional paths. Running these components currently raises a clear NotImplementedError because the corresponding desktop feature still depends on GUI state, a project tree, or a server-backed runtime that has not been extracted into a headless adapter.

Kind	Component names	Desktop codes	Distribution prefix
tool	evaluation	Evaluation	heliokit-tool-evaluation
tool	catch, chimera, chip, chmap, mcchd_cnn	CATCH, CHIMERA, CHIP, CHMAP, MCCHD_CNN	heliokit-tool-chd-*
model	sep, tvd_mhd, transformer, server_dynamic	SEP, TVD-MHD, Transformer, ServerDynamicModel	heliokit-model-*
viz3d	streamline, custom_streamline, particle_tracer, animation	VTK visualization leaf codes	heliokit-viz3d-*
viz2d	error_barchart, synoptic_map, cmf, armf, pb, pb_nrgf, pb_fnrgf, pb_wavelets, pb_newkirk, qfactor_coronal, qfactor_sar, twist_coronal, twist_sar, euv, general	2D visualization leaf codes from the desktop menu	heliokit-viz2d-*