Context
The root README describes fbuild as PlatformIO-compatible, but immediately after pip install fbuild users still lack a scannable command guide showing what to run.
The README should provide this orientation as part of the quick-start flow, before sending users into project setup or the detailed CLI reference.
One syntax detail should be explicit: fbuild has no standalone clean subcommand. Cleaning uses fbuild build --clean or fbuild deploy --clean.
Proposal
Immediately after the pip install fbuild installation block, add a concise “Command Quick Start” section containing two tables.
PlatformIO-compatible workflows
| fbuild |
PlatformIO equivalent |
fbuild build |
pio run |
fbuild build --clean |
pio run --target clean, followed by pio run |
fbuild deploy |
pio run --target upload |
fbuild deploy --clean |
Clean, then pio run --target upload |
fbuild monitor |
pio device monitor |
fbuild ci |
pio ci |
Explain that --platformio delegates build, deploy, and monitor to the installed PlatformIO CLI for A/B comparisons, while fbuild ci provides a compatible fbuild-native CI surface.
Commands unique to fbuild
Add a grouped table containing every remaining top-level command, with a one-line explanation:
- Build and device workflows:
reset, test-emu, compile-many, bringup
- Analysis and developer tooling:
symbols, bloat, clang-tidy, iwyu, clang-query, clangd-config, lib-select
- Dependencies and caches:
sync, purge, cache, lnk
- Runtime and device introspection:
daemon, show, device, serial, port
- Integrations:
mcp
Keep detailed flags and nested subcommands in docs/reference/cli.md; link that reference directly after the quick-start tables.
Acceptance criteria
- A “Command Quick Start” section appears immediately after the README’s
pip install fbuild block.
- Users see the command mapping before the project-creation walkthrough or other detailed documentation.
- The PlatformIO mapping covers build, clean build, upload/deploy, clean deploy, serial monitor, and CI.
- Every example uses valid fbuild syntax and does not imply that
fbuild clean exists.
- The section explains where
--platformio is supported and distinguishes passthrough mode from fbuild-native compatibility.
- A separate grouped table lists every fbuild-only top-level command present in the current CLI when the change lands.
- Each fbuild-only command has a concise, user-oriented description.
- Each command appears exactly once in either the compatibility table or the fbuild-only table.
- The section links to
docs/reference/cli.md for detailed flags, examples, and nested subcommands.
- The inventory is checked against the current Clap command surface or
fbuild --help, including recently added commands such as cache.
- The tables remain concise enough to function as quick-start guidance rather than duplicating the full CLI reference.
Related issues
Context
The root README describes fbuild as PlatformIO-compatible, but immediately after
pip install fbuildusers still lack a scannable command guide showing what to run.The README should provide this orientation as part of the quick-start flow, before sending users into project setup or the detailed CLI reference.
One syntax detail should be explicit: fbuild has no standalone
cleansubcommand. Cleaning usesfbuild build --cleanorfbuild deploy --clean.Proposal
Immediately after the
pip install fbuildinstallation block, add a concise “Command Quick Start” section containing two tables.PlatformIO-compatible workflows
fbuild buildpio runfbuild build --cleanpio run --target clean, followed bypio runfbuild deploypio run --target uploadfbuild deploy --cleanpio run --target uploadfbuild monitorpio device monitorfbuild cipio ciExplain that
--platformiodelegatesbuild,deploy, andmonitorto the installed PlatformIO CLI for A/B comparisons, whilefbuild ciprovides a compatible fbuild-native CI surface.Commands unique to fbuild
Add a grouped table containing every remaining top-level command, with a one-line explanation:
reset,test-emu,compile-many,bringupsymbols,bloat,clang-tidy,iwyu,clang-query,clangd-config,lib-selectsync,purge,cache,lnkdaemon,show,device,serial,portmcpKeep detailed flags and nested subcommands in
docs/reference/cli.md; link that reference directly after the quick-start tables.Acceptance criteria
pip install fbuildblock.fbuild cleanexists.--platformiois supported and distinguishes passthrough mode from fbuild-native compatibility.docs/reference/cli.mdfor detailed flags, examples, and nested subcommands.fbuild --help, including recently added commands such ascache.Related issues
docs/reference/cli.mdas the detailed CLI reference.fbuild cicommand #242 — introducedfbuild cias the PlatformIO-compatible counterpart topio ci.