fbuild accepts either fbuild <subcommand> <project-dir> or
fbuild <project-dir> <subcommand> for project-oriented commands.
Global options:
| Option | Description |
|---|---|
-e, --environment <env> |
Select a platformio.ini environment. |
-v, --verbose |
Print more detail. |
-p, --port <port> |
Select a serial port. |
-c, --clean |
Clean before deploy when used by deploy-compatible paths. |
--monitor[=<flags>] |
Attach monitor after deploy. |
--timeout <secs> |
Set monitor/emulator timeout where supported. |
--halt-on-error <regex> |
Stop monitor/emulator on an error pattern. |
--halt-on-success <regex> |
Stop monitor/emulator on a success pattern. |
--expect <regex> |
Require a pattern in monitor/emulator output. |
--platformio |
Use PlatformIO compatibility mode where supported. |
--shrink[=<mode>] |
Flash-size reduction mode: auto, off, safe, aggressive, or printf. |
--no-shrink |
Disable all shrink optimizations. |
Compile firmware.
fbuild build
fbuild build -e uno
fbuild build --clean
fbuild build --verbose
fbuild build --project-dir /path/to/projectCommon options include --clean, --jobs, --quick, --release,
--platformio, --dry-run, --target compiledb, --symbol-analysis,
--no-timestamp, --output-dir, --shrink, and --no-shrink.
Build and flash firmware, or deploy an existing build with --skip-build.
fbuild deploy
fbuild deploy -e esp32s3 --port COM5
fbuild deploy --clean
fbuild deploy --monitor
fbuild deploy --monitor="--timeout 60 --halt-on-success \"TEST PASSED\""Common options include --port, --clean, --monitor, --timeout,
--halt-on-error, --halt-on-success, --expect, --no-timestamp,
--skip-build, --baud, --to device|emu|emulator, --emulator, and
--output-dir.
Attach to serial output.
fbuild monitor
fbuild monitor -e uno --port COM3 --baud 115200
fbuild monitor --timeout 60 --halt-on-error "TEST FAILED" --halt-on-success "TEST PASSED"Build and run firmware in an emulator, then exit with the emulator result.
fbuild test-emu . -e uno
fbuild test-emu tests/platform/esp32s3 -e esp32s3 --emulator qemu --timeout 10See emulator testing for backend rules and known limitations.
| Command | Purpose |
|---|---|
fbuild reset |
Reset a device without flashing. |
fbuild device list |
List connected devices. |
fbuild device status <port> |
Show detailed device status. |
fbuild device lease <port> |
Acquire a device lease. |
fbuild device release <port> |
Release a device lease. |
fbuild device take <port> --reason <text> |
Preempt the current holder. |
fbuild daemon status |
Show daemon status. |
fbuild daemon stop |
Stop the daemon gracefully. |
fbuild daemon restart |
Restart the daemon. |
fbuild daemon list |
List running daemon instances. |
fbuild daemon kill [--pid <pid>] [--force] |
Kill one daemon process. |
fbuild daemon kill-all [--force] |
Kill all daemon processes. |
fbuild daemon locks |
Show project and serial locks. |
fbuild daemon clear-locks |
Clear stale locks. |
fbuild daemon cache-stats |
Show disk cache statistics. |
fbuild daemon gc |
Run disk cache garbage collection. |
fbuild daemon monitor |
Tail daemon logs. |
fbuild show daemon |
Show daemon logs. |
fbuild purge |
Purge cached packages or run --gc. |
| Command | Purpose |
|---|---|
fbuild symbols <elf-or-project> |
Per-symbol bloat analysis. See symbols.md. |
fbuild bloat graph <input> --symbol <name> |
Render a Graphviz back-reference graph. |
fbuild bloat lookup <input> --symbol <name> |
Inspect one symbol's size and references. |
fbuild lib-select |
Debug LDF-style library selection. |
fbuild clang-tidy |
Run clang-tidy against project sources. |
fbuild iwyu |
Run include-what-you-use analysis. |
fbuild clang-query |
Run a clang-query matcher. |
fbuild lnk pull |
Fetch .lnk resource blobs into the cache. |
fbuild lnk check |
Verify cached .lnk resources. |
fbuild lnk add <url> |
Create a .lnk manifest for a remote blob. |
fbuild mcp |
Start the MCP server for AI assistant integration. |
Build many sketches against one board using a two-stage pipeline: framework and library archives are built once, then sketch compile/link jobs fan out.
fbuild compile-many --board uno examples/Blink examples/Fire2012
fbuild compile-many --board teensy41 --framework-jobs 2 --sketch-jobs 8 --release sketches/*PlatformIO-compatible CI entry point. It maps common pio ci flags onto
compile-many.
fbuild ci --board uno --lib ./libs --lib ./more -c custom.ini \
examples/Blink/Blink.ino examples/Fire2012/Fire2012.inofbuild ci flag |
pio ci equivalent |
Behavior |
|---|---|---|
--board <b>, -b <b> |
--board, -b |
Required board id. |
--lib <path>, -l <path> |
--lib, -l |
Repeatable extra library search path. |
--project-conf <path>, -c <path> |
--project-conf, -c |
Use a shared platformio.ini. |
--keep-build-dir |
--keep-build-dir |
Accepted; fbuild always keeps .fbuild/build/.... |
--build-dir <path> |
--build-dir |
Accepted but not yet honored. |
--framework-jobs, --sketch-jobs, --quick, --release, --verbose |
n/a | fbuild-native controls. |
This file is the user-facing CLI reference. Crate-local README files under
crates/ describe implementation internals. When the Clap command surface
changes, update this reference or add generation/CI validation so it cannot
drift.