CLI Reference

← Home

CLI Reference

• Two binaries
• solarxy: GUI viewer
• solarxy-cli: terminal companion
  • Single-file operations
  • Batch validation
  • Configuration discovery
  • Self-update
• Usage examples
• Input validation

Two binaries

Solarxy ships as two independent binaries since v0.5.0:

Binary	Role	Window?
solarxy	GUI viewer - PBR rendering, inspection, split viewport	Yes - opens a wgpu window
solarxy-cli	Terminal companion - model analysis (TUI / JSON), batch validation, update orchestration, GUI launcher	No (a TUI in --mode analyze)

solarxy-cli --mode view execs the sibling solarxy binary if it lives in the same directory (the winget, Cask, and Flathub bundles install both side by side). On a CLI-only install it prints platform-specific GUI install hints instead.

solarxy: GUI viewer

solarxy [OPTIONS]

Flag	Description	Default
-m, --model <PATH>	Open a model at launch (drag-and-drop also works)	-
--verbose	Verbose logging - equivalent to --log-level solarxy=debug	off
--log-level <DIRECTIVE>	A tracing filter directive (e.g. solarxy=debug). RUST_LOG, if set, overrides this.	-
--help	Print help	-
--version	Print version	-

The GUI binary accepts only these flags - -M, -f, -o, --about, and --update live on solarxy-cli.

solarxy-cli: terminal companion

solarxy-cli [OPTIONS]

Single-file operations

Flag	Description	Default	Applies to
-m, --model <PATH>	Path to a model file	-	required for analyze; optional for view
-M, --mode <MODE>	Operation mode: view or analyze	view	-
-f, --format <FORMAT>	Output format: text or json	text	analyze only
-o, --output <PATH>	Write the report to a file. - is a stdout synonym.	-	analyze / batch validation
--about	Print version, repository, and license	-	-
--update	Self-update, or print the right package-manager command - see Self-update	-	-
--help	Print help	-	-
--version	Print version	-	-

Removed in v0.5.0: --mode preferences and --mode docs. Preferences moved to the GUI Edit → Preferences… dialog (Ctrl/⌘+,); documentation moved to this wiki.

Batch validation

Add --paths to validate many models in one run. The batch validator loads each matched model, applies the validation policy from solarxy.toml, and emits a unified report through the chosen adapter.

--paths requires -M analyze. With the default -M view, solarxy-cli launches the GUI and ignores --paths. Every batch-validation command must include --mode analyze.

A canonical invocation, line-by-line:

solarxy-cli --mode analyze \           # required - selects the batch validator
  --paths "assets/**/*.glb" \           # glob; quote so the shell doesn't expand **
  --config solarxy.toml \               # optional - falls back to discovery if omitted
  --adapter generic \                   # generic or github-actions
  --adapter-format json \               # format the adapter renders (see matrix below)
  --output report.json \                # file path, or - for stdout
  --fail-on error                       # error (default) / warning / never

Flag	Description	Default
--paths <GLOB>…	One or more glob patterns (e.g. 'assets/**/*.glb'). Repeatable. Quote them so the shell doesn't pre-expand **.	-
--config <PATH>	Path to a solarxy.toml. When omitted, discovery applies.	(discovered)
--adapter <NAME>	generic or github-actions	generic
--adapter-format <FORMAT>	json, text, tap, junit-xml, gha-commands, or sarif. Defaults to the adapter's preferred format.	(adapter default)
--fail-on <POLICY>	Exit-code policy: error (validation errors fail), warning (errors or warnings fail), never (always exit 0)	error

Adapter / format support - not every adapter renders every format:

Format	generic	github-actions
json	Yes	Yes
text	Yes	Yes
tap	Yes	Yes
junit-xml	Yes	Yes
gha-commands	No	Yes
sarif	No	Yes

generic defaults to json; github-actions defaults to gha-commands. Asking generic for gha-commands or sarif is an error. The rendered report is written to --output (or stdout); there are no separate side-artifact files. For full pipeline recipes see CI/CD Integration.

Configuration discovery

When --config is not passed, solarxy.toml is resolved via a four-step priority ladder: explicit --config -> $SOLARXY_CONFIG -> nearest solarxy.toml in the start directory -> parent walk up to a .git/ directory or the filesystem root (capped at 20 levels) -> built-in defaults.

The start directory differs by mode:

• Single-file -M analyze -m <model> - the model's parent directory.
• Batch --paths - the current working directory. Run solarxy-cli from your repository root, or pass --config, so discovery resolves the file you expect.

The resolved config path and a SHA-256 of its bytes are embedded in the batch run report, so you can prove which policy validated which assets.

For the full algorithm, the discovery flowchart, and format_version handling, see Configuration -> Discovery order.

Self-update

solarxy-cli --update behaves differently depending on how the CLI was installed:

Installed via	What --update does
Shell installer / PowerShell installer / portable .zip	Self-update via axoupdater
Homebrew formula (solarxy-cli)	Prints brew upgrade solarxy-cli
Flatpak (dev.koljam.solarxy)	Prints flatpak update dev.koljam.solarxy

Running axoupdater against a package-managed install would corrupt it, hence the package-manager fallback.

Usage examples

# Open the GUI on an empty viewport
solarxy

# Open the GUI with a model at launch
solarxy -m model.obj

# GUI with verbose logging / a custom tracing filter
solarxy --verbose -m model.obj
solarxy --log-level solarxy=debug,wgpu_hal=warn -m model.obj

# Analyze a model in the interactive terminal report (TUI)
solarxy-cli --mode analyze -m dragon.glb

# Export a text report to a file
solarxy-cli --mode analyze -m dragon.glb -o report.txt

# Export a JSON report and pipe it to jq
solarxy-cli --mode analyze -m dragon.glb -f json | jq .meshes

# CLI launcher → GUI (execs the sibling solarxy binary)
solarxy-cli --mode view -m dragon.glb

# Batch validation across a glob (note: --mode analyze is required)
solarxy-cli --mode analyze --paths 'assets/**/*.glb'

# Strict gate - fail on any warning
solarxy-cli --mode analyze --paths 'assets/**/*.glb' --fail-on warning

# JUnit XML for GitLab CI / Jenkins
solarxy-cli --mode analyze --paths 'assets/**/*.glb' \
  --adapter generic --adapter-format junit-xml --output report.xml

# GitHub Actions - workflow-command annotations on the PR
solarxy-cli --mode analyze --paths 'assets/**/*.glb' --adapter github-actions

# GitHub Actions - SARIF for Code Scanning
solarxy-cli --mode analyze --paths 'assets/**/*.glb' \
  --adapter github-actions --adapter-format sarif --output solarxy.sarif

# Use a specific config (overrides discovery)
solarxy-cli --mode analyze --paths 'assets/**/*.glb' --config ./ci/solarxy.toml

# Or point at it with an environment variable
SOLARXY_CONFIG=./ci/solarxy.toml solarxy-cli --mode analyze --paths 'assets/**/*.glb'

# Self-update (or print the right package-manager command)
solarxy-cli --update

# Print version, repository, license
solarxy-cli --about

Input validation

solarxy-cli validates -m / --model before proceeding:

Condition	Message
File does not exist	Model file does not exist: <path>
Path is a directory	Path is not a file: <path>
Unsupported extension	Invalid file extension '.<ext>', expected '.obj', '.stl', '.ply', '.gltf', or '.glb'
No file extension	File has no extension, expected '.obj', '.stl', '.ply', '.gltf', or '.glb'
analyze with no -m and no --paths	Model path required for analyze mode

See also: Installation · Configuration · CI/CD Integration · Keyboard Shortcuts · Troubleshooting · User Guide