Skip to content

docs: add command quick start next to README installation #1028

Description

@zackees

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions