Documentation
📘 Commands

RF Swift Command Reference

RF Swift Command Reference

Complete reference for the rfswift command line. Each command has its own page with syntax, options and examples.

Quick Help: rfswift --help shows the grouped overview, rfswift [command] --help the details of one command. The Linux packages also ship man pages (man rfswift-container-create) and bash, zsh and fish completions.
🧙
Interactive Mode: most commands open a TUI picker when a required flag is missing in a terminal. rfswift container create without -i and -n launches the guided wizard, rfswift container shell without -c shows a container picker, and rfswift env update without a name opens the update wizard. Everything degrades to plain flags when scripting or piping.

🗂️ The v4 command tree

RF Swift v4.0 “Nucleus” reorganised the CLI around resources. The old flat commands (rfswift run, rfswift exec, rfswift images pull, rfswift nix install, …) all still work and print a notice pointing at the new spelling, so existing scripts and muscle memory are safe.

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

Canonical and legacy spellings

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. 
# 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 is printed on interactive terminals only. It is skipped when stdout is a pipe (scripts, --json consumers) and when RFSWIFT_NO_BANNER is set.

📋 Command groups

🐳 Containers

container
Create, 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 install
Guided tool installation in a container or Nix environment
 profile
YAML presets for quick container creation
 container stop
Stop a running container
 container rm
Remove a container
 container rename
Rename a container
 container commit
Save a container as a new image
 container last
List recently used containers
 container upgrade
Move a container to a new image

🖼️ Images and portability

image
List, pull, audit, build, tag, export and import images
 image local / remote / pull / versions
Registry browsing, pulling and version tracking
 image build
Build an image from a YAML recipe
 image rm
Delete an image
 image tag
Rename an image tag
 image download
Save an image to tar.gz
 image export
Export containers or images
 image import
Import containers or images

❄️ Native Nix environments

env
Create, enter, update, roll back, audit and export native Nix environments
 Nix engine guide
How the native engine works, isolation, GPU, udev, Windows

⚙️ Runtime configuration

config
Change devices, mounts, capabilities, cgroups, GPUs, ports and ulimits of an existing container
 config bindings
Device and volume bindings
 config capabilities
Linux capabilities
 config cgroups
cgroup device rules
 config gpus
GPU passthrough
 config ports
Exposed and published ports
 config ulimits
Resource limits
 realtime
One-command realtime mode for SDR work

🌐 Networking

network
Managed NAT networks for container isolation

🔌 Devices and host

host
Host setup: udev rules, Docker access, Nix jail, audio server
 usb
USB passthrough on macOS (Lima) and Windows (usbipd)
 macusb
macOS USB backend details
 winusb
Windows USB backend details
 engine
Engine selection, Lima VM management

🛡️ Security

audit
Vulnerability and attack-surface audit of environments, images and containers
 report
Assessment reports from a container and its workspace

📡 Remote access

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

🔧 System and maintenance

system
doctor, cleanup, update, upgrade, log and report under one parent
 doctor
Diagnose the host: engines, Nix, USB, display, audio, udev rules, jail
 cleanup
Remove old containers and images
 update
Update the RF Swift binary
 log
Record and replay terminal sessions
 completion
Shell 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)

🆘 Getting help 

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    # completions
💡
New to RF Swift? Start with the Quick Start Guide before diving into command details.
Last updated on
🛠️ Container Scriptscontainer