CLI reference
Every verb and flag of the rayrf command line, generated from the live argument parsers, so this page always matches the shipped build. Workflows and worked examples are on CLI overview, spec authoring on Scripting and specs.
Local verbs
`rayrf auth`
Manage the local license cache. Activation binds the key + machine id pair on the RayRF licensing service and persists the result so the desktop UI and the CLI both pick it up on next launch. The auth subcommand does not require the headless capability.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--license-key | LICENSE_KEY | License key to activate on this machine. Format: the same string you received by email after subscribing. Case is normalized to upper, surrounding whitespace stripped. | |
--machine-name | MACHINE_NAME | Optional human-readable label for this machine (shown in the account dashboard's seat list). Defaults to the host name. | |
--status | Print the cached license state and perform a fresh server check. Default action when no other flag is given. | ||
--deactivate | Release this machine's seat on the licensing service and clear the local cache. |
`rayrf run`
Run one project or all projects in a folder (sequential).
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project, -p | PROJECT | Path to a single .rfsim/.emflux project file. | |
--folder, -f | FOLDER | Path to a folder containing .rfsim/.emflux projects. | |
--recursive | When using --folder, search recursively. | ||
--backend | BACKEND | Backend to run: cpu, cuda, or a path to a backend executable. Overrides the job file's backend field. If omitted, auto-detected next to the app (CUDA preferred). | |
--air-around, --air-around-mm | AIR_AROUND_MM | Override FDTD air around (mm). | |
--air-above, --air-above-mm | AIR_ABOVE_MM | Override FDTD air above (mm). | |
--air-below, --air-below-mm | AIR_BELOW_MM | Override FDTD air below (mm). | |
--dx, --dx-mm | DX_MM | Override dx (mm). | |
--dy, --dy-mm | DY_MM | Override dy (mm). | |
--dz, --dz-mm | DZ_MM | Override dz (mm). | |
--mesh | uniform / graded | Mesh-style override for manual/advanced meshing. 'uniform' disables grading so dx/dy/dz are the literal cell size everywhere (a true uniform mesh); 'graded' enables board refinement by the per-axis grading multipliers. Default: leave the project's saved setting (in advanced mode that can silently refine the board to dx/mult). | |
--freq-min, --freq-min-mhz | FREQ_MIN_MHZ | Override frequency band minimum in MHz. | |
--freq-max, --freq-max-mhz | FREQ_MAX_MHZ | Override frequency band maximum in MHz. | |
--boundary-condition | BC_ALL | Override boundary condition (e.g. PML8). | |
--eps-r | EPS_R | Override dielectric eps_r. | |
--thickness, --thickness-mm | THICKNESS_MM | Override dielectric thickness (mm). | |
--loss-tangent | LOSS_TANGENT | Override every dielectric layer's loss tangent (tan d). 0 = lossless; typical FR4 ~0.02; low-loss substrates ~0.001-0.005. | |
--fft-length-multiplier, --fft-mult | FFT_LENGTH_MULTIPLIER | Force override FFT length multiplier used for S-parameter post-processing (zero-padding). Must be >= 1. | |
--job | JOB_FILE | Path to a YAML/JSON JobSpec. Overrides all other run flags. | |
--quality | QUALITY | Auto-mode quality. Name ("low"|"medium"|"high"|"very-high"|"med-high") or float in [0,3]. | |
--quality-frac | QUALITY_FRAC | Auto-mode quality as a slider fraction in [0, 1] (multiplied by 3). | |
--sim-mode | auto / advanced | Force simulation mode (auto re-derives from --quality). | |
--convergence, --no-convergence | Enable or disable the mesh-convergence study (--convergence / --no-convergence). When enabled the run repeats up to conv_max_passes backend passes, refining dx/dy/dz by conv_mesh_refine_factor per pass, until the deepest S-parameter dips stabilize within the conv_* thresholds. Omit to use the project's saved setting. | ||
--perf-mode | Performance-benchmark mode: keep mesh/domain at the chosen quality but loosen ringdown to a fixed -20 dB (1e-2 energy ratio) and disable the convergence study so a high-quality CPU run finishes in minutes instead of 30+ minutes. Used by the perf harness. | ||
--max-steps | MAX_STEPS | Hard cap on backend steps. Use to run a fixed-length throughput-only benchmark (e.g. --max-steps 100). When the cap is hit before ringdown, the S-parameter / radiation results are NOT physically valid; intended for kernel-throughput measurement only. | |
--vram-budget-mb | VRAM_BUDGET_MB | Pre-flight VRAM budget in MB. When the auto-derive engine estimates the run will need more VRAM than this, the CLI bails out before launching the backend (writes a manifest with status='vram_overflow_predicted'). No effect in advanced mode. Default: no pre-flight check. | |
--no-surface-currents | Force-disable surface current capture regardless of the project's saved setting. | ||
--no-nf2ff | Force-disable NF2FF far-field capture regardless of the project's saved setting. The far-field DFT is VRAM-resident and scales with the Huygens surface x frequency count, so skipping it on an S-parameter-only run avoids large VRAM use for results that are not needed. | ||
--no-raw-fields | Force-disable the 3D field VTK dumps (every type: E, H, and total energy density) regardless of the project's saved setting. | ||
--skip-geometry-export | Do not write geometry.vtk/geometry.vdb when NF2FF or 3D field export would normally request it. Useful for very large domains when the mesh is not needed. | ||
--dry-run | Apply overrides, validate, export the case, and print the mesh estimate, then stop before launching the backend. Exit 2 if validation finds a blocking error. | ||
--per-face-bc | FACE=TYPE[:MM] | [] | Set a per-face boundary condition (repeatable). FACE is one of x_lo, x_hi, y_lo, y_hi, z_lo, z_hi; TYPE is PML, PEC, or PMC; an optional :MM sets a fixed gap from the geometry to that face, realized exactly as given and overriding the air margins there. Faces without :MM follow the air margins. Example: --per-face-bc z_lo=PEC:2.0. Any per-face setting forces bc_all to Custom. Always give PEC/PMC faces an explicit gap. |
--mesh-preview-size | MESH_PREVIEW_SIZE | Pixel size of the mesh-preview PNG written by --export-mesh. | |
--save-after-run | After the run, save the updated project (in-place unless --save-as is given). | ||
--save-as | SAVE_AS | Path to save the project as after the run (implies --save-after-run). | |
--externalize-results | project / run / off | Where to store run results when the project is saved. 'project' writes results to a sidecar .rfsimout next to the .rfsim and makes that the project's saved default (so the .rfsim can be committed and the .rfsimout gitignored). 'run' does the same for this run only without changing the saved default. 'off' keeps results inside the .rfsim. Omit to use the project's own setting. | |
--out-dir | OUT_DIR | Directory to write exports + run_manifest.json. Default: <project_dir>/_sim_result/<case>. | |
--export-sparams | all / s11 / s21 / none | all | S-parameter CSV/PNG export selection. |
--export-touchstone | Also write Touchstone (.s1p/.s2p). | ||
--export-smith | Write Smith chart PNG. | ||
--export-polar | Write polar radiation pattern PNG (E-plane + H-plane). | ||
--polar-freq-mhz | POLAR_FREQ_MHZ | Target frequency (MHz) for polar plot; nearest available is used. | |
--export-rad3d | Write 3D radiation pattern PNG (PyVista off-screen). | ||
--rad3d-freq-mhz | RAD3D_FREQ_MHZ | Target frequency (MHz) for 3D radiation plot; nearest available is used. | |
--export-rad3d-vtk | Also write radiation pattern as a VTK/VTP file. | ||
--export-rad-pattern | Write a flat radiation-pattern CSV (freq_hz,theta,phi,gain) from NF2FF data. Not a 3D render; runs under --no-3d-renders. | ||
--export-mesh | Write mesh preview PNG (PyVista off-screen). | ||
--export-mesh-vtk | Also copy geometry.vtk into the out dir. | ||
--export-currents | Write surface-currents heatmap PNG at nearest frequency. | ||
--currents-freq-mhz | CURRENTS_FREQ_MHZ | Target frequency (MHz) for surface currents. | |
--export-all | Convenience: enable every export artifact. | ||
--no-3d-renders | Skip PyVista off-screen exports (mesh preview, rad3d). | ||
--set | VAR_SET | [] | Variable override name=value applied before the run (repeatable; parametric-studio). |
--setting | NAME=VALUE | [] | Set any FDTD setting by name (repeatable), gated by the same value gate as the GUI. An unknown name, bad type/enum, or hard-bound value exits 2; a soft-bound value prints one warning and runs as set. See 'rayrf schema --what settings' for the field list. |
`rayrf reprocess`
Recompute S-parameter CSV/PNG from embedded port time-series without running the backend. Updates the project file with refreshed embedded outputs.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project, -p | PROJECT | Path to a single .rfsim/.emflux project file. | |
--folder, -f | FOLDER | Path to a folder containing .rfsim/.emflux projects. | |
--recursive | When using --folder, search recursively. | ||
--fmin, --fmin-mhz | FMIN_MHZ | Override fmin (MHz). | |
--fmax, --fmax-mhz | FMAX_MHZ | Override fmax (MHz). | |
--fft-length-multiplier, --fft-mult | FFT_LENGTH_MULTIPLIER | Override FFT length multiplier used for reprocessing (>= 1). |
`rayrf project`
Build / inspect / mutate a project from a declarative spec.
`rayrf project build`
Build a project from a spec file.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--spec | SPEC | Spec file (.json/.yaml). | |
--out | OUT | Output project (.rfsim). |
`rayrf project export-spec`
Export a project back to a spec.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project | PROJECT | Project (.rfsim). | |
--out | OUT | Output spec (.json/.yaml). |
`rayrf project query`
Machine-readable project readout.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project | PROJECT | Project (.rfsim). | |
--json | Emit JSON (default). |
`rayrf project dump-settings`
Print every FDTD setting with its value, default, units, and description.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project | PROJECT | Project (.rfsim). | |
--json | Emit a machine-readable JSON list. | ||
--changed-only | Only show settings that differ from their default. | ||
--category | CATEGORY | Only show one category (e.g. boundary, mesh, frequency, field_export). | |
--advanced, --no-advanced | Restrict to advanced-only (--advanced) or to non-advanced (--no-advanced) settings. |
`rayrf project set`
Set variable values (validated).
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project | PROJECT | Project (.rfsim). | |
--var | VAR_SET | [] | name=value (repeatable). |
--out | OUT | Output project (defaults to in-place). |
`rayrf schema`
Print the JSON Schema / reference for a file format or contract.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--what | spec / query / settings / shapes / ports / boundaries / manifest / all | all | spec, query, settings, shapes, ports, boundaries, manifest, or all. |
`rayrf guide`
Built-in reference: orientation and topics (workflow, geometry, ports, boundaries, meshing, settings, diagnostics, remote, pitfalls).
| Flag | Value | Default | Meaning |
|---|---|---|---|
topic | TOPIC | Topic to print; omit for the orientation and the topic list. |
`rayrf validate`
Validate a project, spec, or job without running the backend; prints blocking errors and advisory warnings.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project, -p | PROJECT | Project (.rfsim) to validate. | |
--spec | SPEC | Project spec (.json/.yaml) to build and validate. | |
--job | JOB | JobSpec (.json/.yaml) to validate. | |
--json | Emit a machine-readable JSON report. |
`rayrf estimate`
Derive the auto-mode mesh and print cell count, VRAM, boundary sizing, and runtime cost without running the backend.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--project, -p | PROJECT | Project (.rfsim). | |
--quality | QUALITY | Quality name or 0..3 to estimate at (default: the project's saved quality). | |
--json | Emit a machine-readable JSON report. |
`rayrf calc`
RF transmission-line and antenna calculators (microstrip, patch with inset feed, quarter-wave, Smith, cpw, ...). Frequencies in GHz, lengths in mm, impedances in ohm.
| Flag | Value | Default | Meaning |
|---|---|---|---|
calc_kind | microstrip / stripline / cpw / gcpw / diff / embedded / patch / lambda / lambda-diel / qwt / smith | Which calculator to run. | |
--freq | FREQ | Frequency (GHz). | |
--er | ER | Substrate relative permittivity. | |
--h | H | Substrate height (mm). | |
--w | W | Strip width (mm); omit to solve from --z0. | |
--z0 | Z0 | Target/reference impedance (ohm); patch feed target defaults to 50. | |
--s | S | Gap/spacing (mm) for cpw/gcpw/diff. | |
--b | B | Plate spacing (mm) for stripline. | |
--t | T | Copper thickness (mm) for stripline. | |
--h2 | H2 | Cover height (mm) for embedded microstrip. | |
--er2 | ER2 | Cover permittivity for embedded microstrip. | |
--tand | TAND | Loss tangent (microstrip dielectric loss). | |
--z1 | Z1 | Source impedance (ohm) for qwt. | |
--z2 | Z2 | Load impedance (ohm) for qwt. | |
--r | R | Resistance (ohm) for smith. | |
--x | X | Reactance (ohm) for smith. | |
--json | Emit a machine-readable JSON report. |
Remote verbs
The serve and remote verb group runs and drives remote runner boxes. Setup walkthrough: Runner setup.
`rayrf serve`
Run the remote-runner daemon.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--state-dir | STATE_DIR | ||
--name | NAME | runner name (default rayrf-runner) | |
--owner | OWNER | owner account email; only this account gets control, everyone else connects view-only | |
--host | HOST | bind address (default 0.0.0.0) | |
--port | PORT | TCP port (default 8787) | |
--slots | SLOTS | concurrent jobs (default 1) | |
--backend | cpu / cuda | default backend when the JobSpec does not pin one (default cpu) | |
--backend-dir | BACKEND_DIR | directory containing the backend binary (searched first) | |
--advertise | ADVERTISE | reachable host:port to register with the broker so the desktop can discover this runner (e.g. 45.76.170.248:8787). A licensed runner defaults to this machine's own address; on a NAT or container host pass the externally mapped address instead, and pass 'off' to skip account discovery and stay direct-connect only. --install persists it to runner.json. | |
--license-key | LICENSE_KEY | account license key (or set RAYRF_LICENSE_KEY). A Pro account key licenses the runner with no seat consumed: the website signs a machine-bound token per job, and the same key registers with the broker for 'discover by account'. --install persists it to runner.json. The key is never sent to a peer. | |
--allow-unlicensed | development option for a trusted LAN: run jobs without the backend license gate on a runner with no activated license. Without this flag an unlicensed runner refuses to serve. The mode is reported to every connecting client in the handshake. | ||
--open-owner | trusted-LAN option: with no --owner configured, grant owner control to any connecting peer instead of the default view-only role | ||
--install | generate identity + config, print fingerprint | ||
--autostart | also emit a run-on-startup service unit | ||
--health | print status JSON and exit | ||
--servers | print this box's hardware and current load, then exit | ||
--window | run the runner with a status window instead of the console; the editor's "Use this computer as a runner" button starts this. |
`rayrf remote`
Drive a remote runner.
`rayrf remote ls-jobs`
List jobs on a runner.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT |
`rayrf remote status`
Job status.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
job_id | JOB_ID |
`rayrf remote info`
The runner's advertised hardware and version.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT |
`rayrf remote submit`
Submit a pre-exported case dir.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
--case-dir | CASE_DIR | ||
--spec | SPEC | JobSpec JSON | |
--meta | META | metadata JSON | |
--device-index | DEVICE_INDEX | pin a GPU ordinal on a multi-GPU runner | |
--wait | attach and stream to completion |
`rayrf remote poll`
Poll status until terminal or timeout.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
job_id | JOB_ID | ||
--interval | INTERVAL | 5 | seconds between status checks (default 5) |
--timeout | TIMEOUT | give up after this many seconds (0 = no limit) |
`rayrf remote list-files`
List a finished job's result files.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
job_id | JOB_ID |
`rayrf remote fetch`
Download results.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
job_id | JOB_ID | ||
--dest | DEST | ||
--artifacts | auto / ports / pattern / mesh / currents / fields / all |
`rayrf remote cancel`
Cancel a job.
| Flag | Value | Default | Meaning |
|---|---|---|---|
--host | HOST | ||
--port | PORT | 8787 | |
--fingerprint | FINGERPRINT | pinned runner SPKI fingerprint (hex) | |
--account | ACCOUNT | ||
job_id | JOB_ID |
`rayrf remote describe-schema`
Print the JobSpec / ExportSpec / telemetry contract (no connection)