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.

When HELIOKIT_WORKSPACE is set, relative paths resolve under that workspace. Commands with output paths create missing output directories, print planned absolute output paths before execution, and print Completed. after a successful run.

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.

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.

Plotting commands also accept trailing-dimension component selectors for dataset-name arguments. Use DATASET[INDEX] when a reader exposes a multi-component array and the desktop .swimc state selected one component. For example, psp_fld_l2_mag_RTN[1] selects component index 1 from a (N, 3) CDF variable. Indexes are zero-based.

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

These commands require the optional model stack:

python -m pip install "heliokit[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

This pipeline is part of the optional model stack:

python -m pip install "heliokit[models]"

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 and headless visualization

The CLI visualization components below use the native plotting stack for each domain. Matplotlib and VTK commands can open native interactive windows and do not use the PyQt desktop shell. OpenGL domain views such as PB, QFactor, and Twist render through the desktop shader stack in a short-lived CLI process and save a PNG; they do not open an interactive window from the CLI.

1D plotting commands correspond to desktop plot docks whose DATA_TYPE is 1D, such as XY-Line, Histogram, and Error Barchart:

heliokit run viz2d xy_line --input DATA [--x NAME] [--y NAME|NAME[INDEX]] [--epoch-time-format FORMAT] [--x-label TEXT] [--y-label TEXT] [--save PNG] [--no-show]
heliokit run viz2d histogram --input DATA [--array NAME|NAME[INDEX]] [--bins INT] [--range MIN,MAX] [--save PNG] [--no-show]

2D plotting commands correspond to desktop plot docks whose DATA_TYPE is 2D, such as 2D Histogram, 2D CMF, ARMF, and Synoptic Map:

heliokit run viz2d histogram2d --input DATA [--x NAME] [--y NAME] [--bins INT] [--save PNG] [--no-show]
heliokit run viz2d cmf --input DATA [--state 2D_CMF.swimc] [--x NAME] [--y NAME] [--value NAME] [--vector-x NAME] [--vector-y NAME] [--range MIN,MAX] [--radius-range MIN,MAX] [--resample-number INT] [--method linear|nearest|cubic] [--stream-seed X,Y] [--stream-step-size FLOAT] [--stream-step-number INT] [--stream-width FLOAT] [--stream-arrow-count INT] [--stream-color-mode origin|close_open|color] [--stream-close-color COLOR] [--stream-open-color COLOR] [--no-stream] [--colormap NAME[+|-]] [--save PNG] [--no-show]
heliokit run viz2d magnetogram --input DATA [--x NAME] [--y NAME] [--value NAME] [--range MIN,MAX] [--colormap NAME[+|-]] [--save PNG] [--no-show]

Plotting 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. For CDF epoch X axes, xy_line --epoch-time-format accepts the desktop labels hh:mm, hh, MM-dd, yyyy-MM-dd, yyyy-MM, yyyy, MM, dd, and dd hh. It also accepts raw Matplotlib date-format strings such as %H:%M. --x-label and --y-label override the axis labels after data loading; the desktop XY-LINE demo uses time and value.

cmf --state can load a desktop 2D_CMF.swimc file and apply its saved axes, scalar field, vector field, value range, radius range, resampling method, streamline seeds, step size, step count, line width, arrow count, color mode, close/open streamline colors, colormap, and alpha. Explicit CLI options override state values. In close_open mode, closed streamlines default to red and open streamlines default to blue, matching the desktop color combobox initialization. --colormap accepts rainbow+ for forward colors, rainbow- for reversed colors, and treats an omitted suffix as forward. When omitted, both 2D commands use rainbow+. Without --state, cmf uses common CMF variable names (X/Z axes, BT scalar values, and BX/BZ streamlines); omitted --range and --radius-range values are calculated from the loaded data. magnetogram is an alias for synoptic_map; its defaults match 2D_CARTESIAN.swimc: longitude, latitude, and $N(10^{5} cm^{-3})$. Its colorbar is appended to the main plot axes, so the colorbar height matches the plotted axes height.

VTK 3D visualization commands correspond to the desktop VTK visualization window:

heliokit run viz3d volume --input DATA.vti [--array NAME] [--range MIN,MAX] [--color-map cool-to-warm|blue-gold] [--camera-position X,Y,Z] [--camera-focal-point X,Y,Z] [--camera-view-up X,Y,Z] [--view-angle DEG] [--clipping-range NEAR,FAR] [--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. VTK camera options are optional and use comma-separated numeric triples. The cool-to-warm volume color map matches the saved desktop VTK demo state. The VTK renderer background is fixed to the desktop default, Silver.

OpenGL 3D domain views

PB, QFactor, and Twist are 3D OpenGL domain views, but they are not VTK workflows. They read the desktop .swimc state to recover the selected HDF5 datasets and saved render parameters, then render once and save a PNG. The per-dataset transpose setting in data_select_group is applied exactly as it is in the desktop data selector. --save is required. --input can override the data file recorded in the state, and --radius, --theta, --phi, and --value can override dataset names when a state file is not available or needs adjustment.

heliokit run viz3d pb --state STATE.swimc --save PNG [--input DATA.h5] [--radius NAME] [--theta NAME] [--phi NAME] [--value NAME] [--colormap NAME[+|-]] [--disable-gpu]
heliokit run viz3d pb_nrgf --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d pb_fnrgf --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d pb_wavelets --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d pb_newkirk --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d qfactor_coronal --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d qfactor_sar --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d twist_coronal --state STATE.swimc --save PNG [OPTIONS]
heliokit run viz3d twist_sar --state STATE.swimc --save PNG [OPTIONS]

pb-fnrgf, pb-wavelets, pb-newkirk, cq, sq, ct, and sart are aliases. These commands require the desktop runtime or source tree because they use the desktop OpenGL shader files. GPU rendering is used by default. If the GPU/OpenGL probe fails, rerun the same command with --disable-gpu; this enables the existing Mesa/software-rendering environment. --colormap applies to PB output only: rainbow+ is forward, rainbow- is reversed, and a name without a suffix is forward. When omitted, PB uses Greys-. QFactor and Twist save the native OpenGL framebuffer.

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. Components marked with heliokit[models] are installed only with the optional model stack.

Kind	Component names	Desktop codes	Distribution prefix
tool	evaluation	Evaluation	heliokit-tool-evaluation
tool	catch, chimera, chip, chmap	CATCH, CHIMERA, CHIP, CHMAP	heliokit-tool-chd-*
tool	mcchd_cnn (heliokit[models])	MCCHD_CNN	heliokit-tool-chd-mcchd-cnn
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, armf, euv, general	Desktop plot leaf codes that still depend on GUI-specific state	heliokit-viz2d-*