CLI reference — xng docs

One binary, a dozen subcommands. listen and tui are where you live day to day; scan and survey do the legwork of finding signals; station runs a whole site.

Subcommands

Command	Purpose
`listen`	Decode live from an SDR (multi-channel; mode via `--mode`).
`decode`	Decode from a recorded IQ file.
`tui`	Interactive terminal UI — live, or replay a file with `--file`.
`scan`	Auto-scan known frequency plans and propose a ready-to-run config.
`survey`	Soak-test one mode across all channels; report per-channel stats and advice.
`station`	Run a whole station from a TOML config (many modes/SDRs in one process).
`status`	Show a running station’s sessions and live decode status.
`devices`	List available SDR devices (native Airspy + SoapySDR).
`iq-info`	Inspect a recorded IQ file: duration, power, spectral peaks.
`ingest`	Run the reference asf-2.0 ingest server (gRPC and/or QUIC).
`extern`	Wrap an external decoder (dumphfdl / dumpvdl2 / acarsdec) onto the xng bus.
`selftest`	Built-in end-to-end pipeline sanity check.

Global flags

-v / -vv / -vvv

Increasing verbosity.

--decode-threads <n>

Worker threads for decoding. Defaults to all cores — matters most for the Iridium burst hunter.

Tuning flags

-m, --mode

Which decoder to run. See Modes.

-r, --sample-rate

Capture rate in Hz. Must be an integer multiple of the mode’s channel rate.

-c, --center-freq

Center frequency. Accepts M / k suffixes (e.g. 131.500M).

--channels

Comma-separated channel list, suffix-aware (e.g. 131.550,131.725).

--receiver-pos lat,lon

Required for ADS-B surface positions and AIS/APRS own-ship correlation.

--demod-effort max|live

live keeps every mode real-time on Pi-class hardware; max squeezes out the last few frames.

--sdr "driver=…" · -g, --gain

Device string and front-end gain in dB (AGC if omitted).

Output & filtering flags

All the destination flags from Inputs & outputs, plus:

--filter-labels H1,Q0 · --exclude-labels SQ

Keep or drop ACARS messages by label.

--gs-file stations.json

VDL2 ground-station name lookup (hex AVLC address → name).

--aircraft-db <csv>

tar1090 / Mictronics database for registration and type tagging.

--iridium-satmap

SGP4 satellite labeling for Iridium.

What it looks like running

xng status against a running station:

text

  KE-KSEA-1   up 3h12m   41 aircraft · 7 vessels
  ┌────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────┐
  │ SDR    │ Serial │ Mode    │ Tuning              │ Status                            │
  ├────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────┤
  │ rtlsdr │ 001    │ ACARS   │ 11 ch @ 130.940 MHz │ decoding · 4218 msgs · last now   │
  │ airspy │ —      │ IRIDIUM │ 1 ch @ 1624.000 MHz │ decoding · 240 msgs · last 4s ago │
  └────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────┘

Every subcommand supports --help. survey has its own set (--tune-gain, --scan, --duration, --interim,--show-messages, --out) for dialing in a new site.