Command reference

Every rfswift command with its syntax, options and examples, grouped by what it manages.

Reference · 8 min read · Updated September 27, 2026

Every rfswift command has its own page, with its syntax, options and examples. You don’t need to read this reference to get started: the Quick start covers the few commands most people use every day. Come here when you need a specific option.

New to the command line?

You never have to remember flags. Most commands open an interactive picker when something is missing: rfswift container create with no options starts a guided wizard, and rfswift container shell with no name lets you pick a container from a list. Prefer windows and buttons? The Workbench does the same things without typing.

The 10 commands you’ll use most

You want to… Command
Check that your computer is ready rfswift doctor
Create a lab (guided) rfswift container create
Create a lab from a toolbox rfswift container create -i sdr_light -n mylab
Go back into a lab rfswift container shell -c mylab
See your labs rfswift container last
Download a toolbox rfswift image pull -i sdr_full
See which toolboxes exist rfswift image remote
Add a device to an existing lab rfswift config bindings add -c mylab -d -t /dev/ttyUSB0
Stop or delete a lab rfswift container stop -c mylab / rfswift container rm -c mylab
Update RF Swift rfswift update

Getting help in the terminal

bash
rfswift --help                      # grouped overview
rfswift container create --help     # one command
rfswift config bindings add --help  # a subcommand
man rfswift-env-update              # Linux packages ship man pages
rfswift completion zsh --install    # tab completion

rfswift env update without a name also opens a guided wizard. In scripts and pipes, every command works with plain flags and never waits for input.

The v4 command tree

Since v4.0 “Nucleus”, commands are grouped by what they act on: containers, images, Nix environments, configuration, the host, and so on. The older flat commands (rfswift run, rfswift exec, rfswift images pull, rfswift nix install, …) still work and print a notice with the new name, so existing scripts keep working.

output
rfswift
├── container   create | shell | last | install | stop | rm | rename | commit | upgrade
├── image       local | remote | pull | rm | build | tag | download | export | import | audit | versions
├── env         catalog | list | info | shell | run | install | search | tools | remove | export | import
│               update | rebuild | rollback | generations | audit | gc | gl | udev | versions | wsl (Windows)
├── config      bindings | capabilities | cgroups | gpus | ports | ulimits | serial-hotplug
├── network     create | list | remove | cleanup
├── host        setup | udev | docker-access | isolate | devclean | audio
├── usb         list | attach | detach | status | vm-devices (+ bind | unbind on Windows)
├── audit       <environment | image | container>
├── agent       (serve) | certs init | certs client | certs export | certs import
├── profile     list | show | create | init | delete
├── realtime    enable | disable | status
├── engine      lima status | set | reconfig | reset (macOS)
└── system      doctor | cleanup | update | upgrade | log | report
Old command names (v3 and earlier) and their v4 equivalents
Canonical (v4) Legacy (still works) Short aliases
rfswift container create rfswift run rfswift create, rfswift new
rfswift container shell rfswift exec rfswift shell, rfswift enter
rfswift container stop rfswift stop rfswift halt
rfswift container rm rfswift remove rfswift rm
rfswift container last rfswift last
rfswift container install rfswift install
rfswift container rename / commit / upgrade rfswift rename / commit / upgrade
rfswift image pull / local / remote / versions / audit rfswift images pull / …
rfswift image build / rm / tag / download / export / import rfswift build / delete / retag / download / export / import
rfswift env ... rfswift nix ...
rfswift config ports bind rfswift ports bind rfswift cfg ports bind
rfswift system doctor / cleanup / update / log / report rfswift doctor / cleanup / update / log / report rfswift admin ...
rfswift agent rfswift remote
rfswift usb ... rfswift macusb ... (macOS), rfswift winusb ... (Windows)

The runtime-configuration groups (bindings, capabilities, cgroups, gpus, ports, ulimits) and the maintenance commands (doctor, cleanup, update, log, report) exist both at the top level and under their config / system parent. Neither form is deprecated.

Global flags

Flag Description
--engine auto|docker|podman|lima|nix Engine to use. Precedence: this flag, then RFSWIFT_ENGINE, then [general] engine in config.ini, then auto-detection. nix selects the native Nix engine.
--gpu macOS Apple Silicon only: use the GPU-accelerated Lima VM (krunkit, Vulkan). Implies --engine lima, provides GPU compute but no USB passthrough.
-q, --disconnect Disconnected mode: no update check, no network query.
-v, --version Print the version and exit, without touching the network or an engine.
bash
# Work without querying for updates
rfswift -q container create -i sdr_full -n work

# Run the same command natively with the Nix engine
rfswift --engine nix container create -i sdr_light -n radio

# Set an engine once for the shell session
export RFSWIFT_ENGINE=podman

The ASCII banner only appears in an interactive terminal. It is skipped when the output goes to a pipe (scripts, --json consumers) and when RFSWIFT_NO_BANNER is set.

Command groups

Containers

containerCreate, enter, stop, remove, rename, commit and upgrade containers container create (run)Create and start a new container, all options container shell (exec)Enter a container or run a command in it container installGuided tool installation in a container or Nix environment profileYAML presets for quick container creation container stopStop a running container container rmRemove a container container renameRename a container container commitSave a container as a new image container lastList recently used containers container upgradeMove a container to a new image

Images and portability

imageList, pull, audit, build, tag, export and import images image local / remote / pull / versionsRegistry browsing, pulling and version tracking image buildBuild an image from a YAML recipe image rmDelete an image image tagRename an image tag image downloadSave an image to tar.gz image exportExport containers or images image importImport containers or images

Native Nix environments

envCreate, enter, update, roll back, audit and export native Nix environments Nix engine guideHow the native engine works, isolation, GPU, udev, Windows

Runtime configuration

configChange devices, mounts, capabilities, cgroups, GPUs, ports and ulimits of an existing container config bindingsDevice and volume bindings config capabilitiesLinux capabilities config cgroupscgroup device rules config gpusGPU passthrough config portsExposed and published ports config ulimitsResource limits realtimeOne-command realtime mode for SDR work

Networking

networkManaged NAT networks for container isolation

Devices and host

hostHost setup: udev rules, Docker access, Nix jail, audio server usbUSB passthrough on macOS (Lima) and Windows (usbipd) macusbmacOS USB backend details winusbWindows USB backend details engineEngine selection, Lima VM management

Security

auditVulnerability and attack-surface audit of environments, images and containers reportAssessment reports from a container and its workspace

Remote access

agentServe the engines of a lab machine to authenticated remote clients (mTLS) Remote agent guideSetup, credential files, Workbench connection, limits

System and maintenance

systemdoctor, cleanup, update, upgrade, log and report under one parent doctorDiagnose the host: engines, Nix, USB, display, audio, udev rules, jail cleanupRemove old containers and images updateUpdate the RF Swift binary logRecord and replay terminal sessions completionShell completion scripts

Quick reference

Command Purpose
rfswift container create -i IMAGE -n NAME Create a new container
rfswift container create --profile sdr-full -n NAME Create a container from a profile
rfswift --engine nix container create -i sdr_light -n NAME Create a native Nix environment
rfswift --engine nix container create -i sdr_light -n NAME --isolate Same, inside the bubblewrap / Seatbelt jail
rfswift container shell -c NAME Enter a container (starts it if stopped)
rfswift env shell NAME Enter a Nix environment
rfswift container last List recent containers
rfswift container install -c NAME Pick and run an install function
rfswift image pull -i sdr_full Download an image
rfswift image audit penthertz/rfswift_resolute:sdr_full Scan an image for CVEs
rfswift audit NAME Audit a container, image or Nix environment (auto-detected)
rfswift env catalog Nix environments you can create
rfswift env update --check NAME Preview a Nix environment update
rfswift env rollback NAME Restore the previous generation
rfswift config bindings add -c NAME -d -t /dev/ttyUSB0 Add a device to an existing container
rfswift config serial-hotplug on -c NAME Hot-pluggable serial ports
rfswift config ports bind -c NAME -b 8080:80/tcp Publish a port
rfswift realtime enable -c NAME Realtime SDR mode
rfswift network create -n lab Create an isolated NAT network
rfswift host setup udev rules, engine install, Nix, Docker access, jail
rfswift host udev RF Swift’s udev rules (rootless Podman, Nix)
rfswift host docker-access docker group + socket ACL, no logout
rfswift host audio enable Host audio server for containers (Linux, macOS)
rfswift usb attach Forward a USB device (macOS Lima, Windows usbipd)
rfswift agent certs init --dir DIR --host HOST Generate remote-agent certificates
rfswift agent --bundle DIR Serve this machine’s engines remotely
rfswift doctor Diagnose the environment
rfswift system cleanup all --dry-run Preview a cleanup
rfswift log replay -i FILE.cast Replay a session
rfswift report generate -c NAME -f html HTML assessment report
rfswift engine lima status Lima VM status (macOS)
rfswift update Update RF Swift (or tells you to use your package manager)