The Betaflight Command Line Interface (CLI) is one of the most powerful tools available to FPV pilots, yet it remains underutilized by many builders. While the graphical configurator handles most common tasks, the CLI provides access to advanced settings, diagnostic capabilities, and batch configuration that can dramatically improve your workflow. Whether you are troubleshooting a stubborn build, migrating settings between quads, or fine-tuning performance parameters, mastering the CLI is an essential skill.
Accessing the CLI
Connect your flight controller to your computer via USB and open Betaflight Configurator. Click the “CLI” tab on the left sidebar. You will see a terminal window with a prompt that reads # — this indicates the CLI is ready for commands. The CLI is case-insensitive, so DUMP and dump produce the same result.
Before making any changes, always run diff all and save the output. The diff command shows only settings that differ from Betaflight defaults — this is your custom configuration. Copy this output to a text file. If you ever need to restore your setup, paste the entire diff back into the CLI and type save.
Essential Diagnostic Commands
status — Your First Troubleshooting Command
The status command is the single most useful diagnostic tool in the CLI. It displays real-time information about your flight controller’s state, including CPU load, arming disable flags, I2C errors, and cycle time. When your quad refuses to arm, status will show you exactly which arming disable flag is active. Common flags include RX_FAILSAFE (no receiver signal), CALIBRATING (gyro still initializing), and ANGLE (quad not level enough).
tasks — Monitor CPU Load
The tasks command displays every process running on your flight controller, their execution rates, and CPU utilization. Watch for any task consuming more than 70% of its cycle time — this indicates your CPU is overloaded, which can cause erratic flight behavior. If your CPU load is high, reduce your PID loop rate (8kHz → 4kHz) or disable unused features like accelerometer, barometer, or LED strips.
dma — Direct Memory Access Status
The dma command shows DMA channel assignments for timers and peripherals. DMA conflicts are a common cause of motor outputs not working properly. If motor 1 works but motor 2 does not, a DMA conflict between the motor output timer and another peripheral (like an LED strip) is likely the culprit. Use dma to identify conflicts and reassign resources with resource and timer commands.
Configuration Management Commands
dump vs diff — Understanding the Difference
dump outputs every single setting on the flight controller — all 2,000+ of them. diff outputs only settings that differ from Betaflight defaults. For backup purposes, always use diff all. This captures your custom configuration in a compact format that can be pasted directly into a new flight controller. The dump command is useful for deep debugging but impractical for migration.
diff all — Complete Custom Configuration Backup
Run diff all before making any changes to your quad. This command shows your ports configuration, mixer settings, servo/feature/motor configurations, profile settings, and rate profile settings — everything that makes your quad fly the way it does. I maintain a folder of diff all outputs for every quad I build. When a flight controller needs replacement, I paste the saved diff into the new board and the quad is ready to fly immediately.
get / set — Reading and Writing Individual Parameters
The get command searches for parameters matching a pattern. For example, get gyro_lpf shows all gyro low-pass filter settings. The set command changes a specific parameter: set gyro_lpf1_static_hz = 250. To see the current value of a single parameter, use get with the exact parameter name, or just scroll through the diff output.
Advanced Power-User Commands
resource — Remapping Hardware Pins
The resource command lets you remap hardware functions to different pins. This is crucial when you have a damaged pad or need to use an alternative pin for a UART, motor output, or LED strip. To remap motor 1 from pin B00 to pin B01, first check current assignments with resource, then use resource MOTOR 1 B01 followed by save. Always verify with resource before saving.
timer — Configuring Timer Outputs
Motor outputs require timer-capable pins. The timer command shows which timers are assigned to which pins. If you remap a motor with resource, you may also need to assign a timer: timer B01 AF2. The AF (alternate function) number depends on the MCU — consult your flight controller’s datasheet or the Betaflight target documentation.
defaults — Factory Reset
The defaults command resets all settings to Betaflight defaults for the current target. Use this with caution — it wipes everything. The recommended workflow is: diff all (save your config), defaults (reset), save (reboot), then paste your saved diff back in and save again. This is the most reliable way to resolve persistent configuration corruption.
Practical CLI Workflows
Migrating Settings to a New Flight Controller
1. On the old FC, run diff all and copy the entire output. 2. On the new FC (already flashed with the correct Betaflight target), connect and paste the diff into the CLI. 3. Type save and press Enter. The new FC reboots with all your settings. 4. Verify motor directions and do a hover test before flying. This process takes under 2 minutes.
Batch Configuring Multiple Quads
If you build multiple quads with similar configurations, create a “base diff” template. Customize it for each quad’s specific motor layout and port assignments, then paste it into each FC. This ensures consistent behavior across your fleet while allowing individual customization where needed.
Safety and Best Practices
- Always backup diff all before changes: This is your undo button. No exceptions.
- Remove props before CLI configuration: Many CLI changes require
save, which reboots the FC. Motors can spin unpredictably during reboot. - Verify with status after changes: Check that no arming disable flags appeared after your modifications.
- Use diff, not dump, for backups: Diffs are portable between Betaflight versions. Full dumps may contain version-specific settings that cause issues.
- Test hover after any CLI changes: Even seemingly minor changes can affect flight behavior.
Conclusion
The Betaflight CLI is not just for developers — it is a practical tool that every serious FPV pilot should be comfortable using. From diagnosing arming issues with status to migrating configurations with diff all, the CLI gives you complete control over your flight controller. Spend 30 minutes exploring these commands with a spare FC on your bench, and you will be surprised how much faster and more confidently you can build and troubleshoot your quads.