Skip to main content

CLI flag reference

rtl_433 is a single-binary C program for receiving and decoding the short data bursts that ISM-band devices — weather stations, tyre-pressure sensors, remotes, utility meters — transmit on bands such as 433.92, 315, 868, and 915 MHz. It takes IQ samples from an RTL-SDR or SoapySDR device (or a saved file), runs them through its built-in protocol decoders, and emits structured output.

This page is a grouped quick-reference for the flags you reach for most often. The groups follow the structure of the program's own usage output: general, tuner / input, demodulator and decoders, analysis and debug, file I/O, and data output. Arguments and defaults are taken from the rtl_433 man page and the usage text printed by rtl_433 -h.

note

The full flag set is large and a handful of options change between releases. Always treat rtl_433 -h on your installed build as the authoritative list — it prints the exact flags, sub-keywords, and defaults that binary supports. The tables below cover the common, stable flags.

General options​

FlagArgumentMeaning
-V—Print the version string and exit
-h—Print usage help and exit
-v—Increase verbosity; repeatable (-v, -vv, -vvv, -vvvv)
-c<path>Read config options from a file (may be given more than once)
Check the version and the full help text
rtl_433 -V
rtl_433 -h

A config file holds the same settings as the flags, one directive per line. See the project's conf/rtl_433.example.conf for the directive names that mirror these flags.

Tuner and input options​

These flags choose the radio and the slice of spectrum to listen on.

FlagArgumentMeaningDefault
-ddevice specSelect the input device (RTL-SDR index/serial, SoapySDR query, rtl_tcp, or help)first RTL-SDR
-g<gain> | helpTuner gain in dB, or per-element list for SoapySDRauto
-t<settings>Apply a list of keyword=value settings to the SDR device—
-ffrequencyReceive frequency; repeatable to listen on several frequencies433920000 Hz
-H<seconds>Hop interval used when more than one -f is given600
-p<ppm_error>Correct the tuner frequency-offset error in ppm0
-ssample rateSDR sample rate250000 Hz
-DmodeInput device run mode: quit, restart, pause, manualquit
Select a dongle by serial and tune the 868 MHz band
rtl_433 -d :7a3f -f 868M -s 1024k
tip

Frequencies, sample rates, and intervals accept the SI suffixes k, M, and G — 433.92M, 1024k, and 250k are all valid. Prefer selecting a dongle by serial (-d :SERIAL) over by index (-d 0); USB enumeration order is not stable across reboots, so an index can silently point at the wrong device.

Demodulator and decoder options​

These flags control which protocol decoders run and how pulses are detected.

FlagArgumentMeaning
-R<device>Enable only the listed decoder protocol; repeatable. A negative number disables that protocol (e.g. -R -8). -R 0 disables all decoders
-X<spec>Add a flexible, general-purpose ("flex") decoder defined inline as key=value pairs
-YmodeFSK pulse-detector mode and levels: auto, classic, minmax, level=<dB>, minlevel=<dB>, minsnr=<dB>, autolevel, squelch, ampest, magest

By default the decoders that have proper validation are enabled. Use negative -R numbers to switch specific ones off, or list positive -R numbers to run only those.

Run only protocols 8 and 40 (illustrative protocol numbers)
rtl_433 -R 8 -R 40
Disable two noisy decoders, keep everything else
rtl_433 -R -8 -R -19
info

Protocol numbers are not stable across releases — they shift as decoders are added or removed. Run rtl_433 -R help to print the numbered list that matches your installed build before hard-coding any -R numbers in a script or service unit.

For building a custom -X flex decoder (modulation type, pulse timings, bit matching), see the dedicated flex-decoder page in this knowledge base.

Analysis and debug options​

Use these when a device is not yet decoded and you need to inspect the raw pulses.

FlagArgumentMeaning
-A—Pulse analyzer: analyse pulses and attempt a decode. Pair with -R 0 to suppress normal decoders and see analyzer output only
-y<code>Verify decoding of supplied test data
Analyzer-only run on a captured file
rtl_433 -r capture.cu8 -R 0 -A

The analyzer prints the timing of detected pulses and gaps and a guess at the modulation, which is the usual starting point for writing a new -X flex decoder.

File I/O options​

rtl_433 can read from and write to IQ sample files instead of (or alongside) a live receiver.

FlagArgumentMeaning
-r<filename>Read IQ data from a file instead of a connected receiver
-w<filename>Save the data stream to a file (append)
-W<filename>Save the data stream to a file (overwrite)
-SmodeSignal auto-save — one file per detected signal: none, all, unknown, known. Saves raw IQ samples (uint8 PCM, 2 channel)
Replay a saved capture through the decoders
rtl_433 -r weather_433.cu8
tip

Capturing once with -w and then iterating offline with -r is the fastest way to develop or debug a decoder: you decode the same signal repeatedly instead of waiting for the real device to transmit again.

Data output options​

These flags shape what comes out of rtl_433 after a successful decode.

FlagArgumentMeaning
-FformatOutput format / sink; repeatable to emit several at once: log, kv, json, csv, mqtt, influx, syslog, trigger, rtl_tcp, http, null. Append :<filename> (or a host spec) to write to a file or service
-MmetadataAdd metadata to each record: time[:<opts>], protocol, level, noise[:<secs>], stats, bits
-KtagAdd an expanded token or fixed tag to every output line (FILE, PATH, <tag>, or <key>=<tag>)
-CunitsConvert units in decoded output: native, si, customary
-T<seconds>Run for a fixed duration, then exit; also accepts 12:34 or 1h23m45s
-Eactionhop or quit after outputting a successful event
-n<value>Stop after processing this many samples

Most -F sinks take an optional target. A bare keyword writes to standard output; appending a path or host spec redirects it:

Append a path to write a format to a file
rtl_433 -F csv:/var/log/rtl_433/sensors.csv
Emit JSON to stdout and publish to MQTT at the same time
rtl_433 -F json -F "mqtt://broker.local:1883"
Add ISO timestamps and the protocol number to every record
rtl_433 -F json -M time:iso -M protocol

A complete example​

Illustrative example — the dongle serial, frequencies, MQTT host, and protocol numbers below are made up to show several flag groups working together. Replace them with values for your own hardware and broker.

Illustrative: named dongle, two bands, filtered decoders, JSON + MQTT
rtl_433 \
  -d :7a3f \
  -f 433.92M -f 915M -H 30 \
  -s 1024k -g 400 -p 51 \
  -R 8 -R 40 \
  -M time:iso -M protocol -C si \
  -F json \
  -F "mqtt://broker.local:1883,events=rtl_433[/model]"

Reading the flags in groups: it selects the dongle by serial (-d), hops between two bands every 30 seconds (-f/-H), sets radio parameters (-s/-g/-p), runs only two decoders (-R), adds ISO time plus protocol metadata in SI units (-M/-C), and emits both line-delimited JSON to stdout and MQTT messages to a broker (-F).

Sources​