CLI overview

The rayrf command line builds, inspects, validates, runs, and post-processes .rfsim projects headless, driving the same solver as the desktop app. This page covers invocation, licensing, the verbs, an end-to-end workflow, and the exit codes and machine-readable output an agent depends on.

Invocation

The CLI exports a case and launches the backend for you. You never call the solver directly.

rayrf run --project patch.rfsim --quality medium    bare form, latest CLI version
rayrf --cli-v1 run --project patch.rfsim            pin the CLI version

The bare rayrf <verb> form routes to the latest CLI version. rayrf --cli-v1 <verb> pins the version so a script keeps working across releases. From a source checkout the entry point is python app.py, so the same commands read python app.py --cli-v1 run .... Every example here uses the packaged rayrf form.

On Windows the install folder (%LOCALAPPDATA%\Programs\RayRF Studio) ships the console launcher rayrf.com next to the windowed RayRF.exe. A shell resolves rayrf to the launcher, which waits and streams output. On Linux the AppImage itself is the command: ./RayRF-Studio-1.1.9-x86_64.AppImage run .... A launch with no arguments opens the desktop app, and an argument that is not a verb or a project file prints the unknown command and exits 2.

Licensing

Headless runs need a Pro-tier license, which carries the CLI capability (CAP_CLI). The auth, schema, guide, and calc verbs work with no license, and remote describe-schema does too, so an agent can read the contracts and size a design before activating. Every other verb, including validate and estimate, refuses without CAP_CLI and exits 2 with one line on stderr.

rayrf auth --license-key KEY    activate this machine (shared with desktop sign-in)
rayrf auth --status             show cached state and re-check with the server
rayrf auth --deactivate         release this machine's seat

Activation binds the key to this machine and stores the result where the desktop app reads it, so signing in from either surface covers both.

Verbs

Nine local verbs plus the serve and remote group. Each --help lists its flags, and CLI reference documents every one.

End-to-end workflow

Size the geometry with a calculator, build the project from a spec, inspect and check it, run it, then re-post-process without re-running.

# 1. Size a 50 ohm microstrip feed on an FR4 stackup.
rayrf calc microstrip --freq 3.0 --er 4.4 --h 1.6 --z0 50 --json

# 2. Build the project from a spec (schema --what spec is the format).
rayrf project build --spec patch.json --out patch.rfsim

# 3. Inspect what you built.
rayrf project query --project patch.rfsim
rayrf project dump-settings --project patch.rfsim --changed-only

# 4. Check it before paying for a run.
rayrf validate --project patch.rfsim --json
rayrf estimate --project patch.rfsim --quality medium

# 5. Run with a quality preset and the exports you want.
rayrf run --project patch.rfsim --quality medium \
  --export-sparams all --export-touchstone --save-after-run

# 6. Re-post-process the embedded time series over a new band.
rayrf reprocess --project patch.rfsim --fmin 4000 --fmax 7000

rayrf run --dry-run applies overrides, validates, exports the case, and prints the mesh estimate without launching the backend. rayrf guide workflow prints this recipe offline. A project saved with --save-after-run or --save-as opens in the desktop app with the S-parameters and radiation pattern tabs populated from the embedded results.

Quality grammar

The --quality flag on run and estimate takes a name, a midpoint, or a number. The names are low, medium (alias med), high, and very-high, mapping to 0, 1, 2, and 3. The three midpoints are low-med (0.5), med-high (1.5), and high-vhigh (2.5), and any decimal in [0, 3] sets the value directly. run --quality-frac instead takes a slider fraction in [0, 1], multiplied by 3. A value outside the range is refused, never clamped.

Exit codes

Scripts branch on the code. The stderr message is one line unless RAYRF_CLI_TRACEBACK=1 is set.

A missing or sub-Pro license, a bad flag, an unknown --setting, or an out-of-range --quality all exit 2 before the backend launches.

Machine-readable output

--json emits a machine-readable report from validate, estimate, calc, project query, and project dump-settings. The remote subcommands print JSON to stdout and human text to stderr, so a caller reads stdout and logs stderr. Every run writes run_manifest.json into the out dir with the resolved parameters, the auto-derived mesh and its reasoning, performance figures, and the artifact list. Scripting and specs documents the manifest.

Environment variables

Driving the CLI from an agent

rayrf guide and its topics are bundled with the executable as offline orientation, and rayrf schema --what all prints the machine-readable contract for every file format. The CLI reference lists every verb and flag, Scripting and specs covers the spec and JobSpec formats, and the docs landing page offers the whole reference as a single-file download to load into an agent's context.