# Command reference Every espx command with its arguments and flags, as the CLI defines them. Every command takes `--help`. `espx --version` (or `-V`) prints the version. No command waits for input unless it takes `-i` and you pass it. | Command | Does | | ------------------------------ | ------------------------------------------------------------------------------ | | [`setup`](#espx-setup) | Install the esp-rs tools and Rust targets | | [`new`](#espx-new) | Create a project with esp-generate | | [`build`](#espx-build) | `cargo build --release` with a size check | | [`flash`](#espx-flash) | Build and `cargo espflash flash --release` | | [`run`](#espx-run) | Build, flash and monitor | | [`monitor`](#espx-monitor) | Watch a board's serial output | | [`replay`](#espx-replay) | Play back a recording | | [`erase`](#espx-erase) | Erase a board's whole flash | | [`clean`](#espx-clean) | `cargo clean` | | [`devices`](#espx-devices) | List attached boards | | [`info`](#espx-info) | Read a board's chip, flash size and MAC | | [`chips`](#espx-chips) | List supported chips | | [`boards`](#espx-boards) | List known dev boards, or name an attached one | | [`board`](#espx-board) | Print one dev board's pins | | [`deps`](#espx-deps) | Resolved esp-hal crate versions | | [`context`](#espx-context) | What an agent needs to write firmware here | | [`doctor`](#espx-doctor) | Check the toolchain, offline | | [`env`](#espx-env) | Shell exports for the tools | | [`agent`](#espx-agent) | Show or change what AI agents may do | | [`log`](#espx-log) | The agent audit log | | [`mcp`](#espx-mcp) | Serve MCP, or add espx to an MCP client | | [`update`](#espx-update) | Update espx to the latest signed release (the app's copy updates with the app) | | [`uninstall`](#espx-uninstall) | Remove what `setup` installed | ## espx setup Install the esp-rs tools into `~/.espx/bin` and the Rust targets for your chips. Idempotent. ```sh espx setup [--chip |all] [--shell] ``` | Flag | Meaning | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--chip LIST` | Chips to set up, comma-separated, or `all`. Default: every RISC-V chip. Xtensa chips (esp32, esp32s2, esp32s3) also install Espressif's Rust fork through espup | | `--shell` | Append `eval "$(espx env)"` to your shell config (`~/.zshrc` or `~/.bashrc`) so plain cargo finds the tools | See [Installation](https://www.espx.dev/docs/installation) and [Xtensa chips](https://www.espx.dev/docs/reference/xtensa). ## espx new Create a bare-metal Rust project for a chip with esp-generate, plus a README and `AGENTS.md`. ```sh espx new [--chip C] [--board B] [--dir .] [--port P] [--board-id ID] [-o OPT]... [-i] ``` | Argument or flag | Meaning | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `NAME` | Project name; the project is created in `DIR/NAME` | | `--chip C` | Chip to target (see `espx chips`). Default `esp32c6`, or the board's chip | | `--board B` | Board model to target (see `espx boards`); selects its chip and records its pins | | `--dir DIR` | Directory to create the project in. Default `.` | | `--port P` | Pin the board's serial port in `espflash_ports.toml` | | `--board-id ID` | Bind the project to a physical board (its id, port or name) in `espx.toml`'s `[board]` section | | `-o`, `--option OPT` | Extra esp-generate option (`wifi`, `embassy`, `alloc`, `defmt`, `probe-rs`, ...). Repeatable. `log` is on unless `defmt` is given | | `-i`, `--interactive` | Pick options in esp-generate's terminal UI instead of headless generation | See [Projects](https://www.espx.dev/docs/cli/projects). ## espx build Build the project with `cargo build --release`, then report the image and RAM size and check the image fits the app partition. ```sh espx build [--dir .] [--json] [-- ] ``` | Flag | Meaning | | ----------- | --------------------------------------------------------------------- | | `--dir DIR` | Project directory. Default `.` | | `--json` | Newline-delimited JSON events on stdout: `diagnostic`, `size`, `done` | | `-- ARGS` | Extra arguments for `cargo build` | ## espx flash Build and flash the project with `cargo espflash flash --release`. ```sh espx flash [--dir .] [--port P] [--baud B] [--monitor] [-i] [--json] [-- ] ``` | Flag | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--dir DIR` | Project directory. Default `.` | | `--port P` | Board: a port, a board id or a name. Default: `[board] id` in `espx.toml`, `espflash_ports.toml`, or the single connected board | | `--baud B` | Flashing speed. Default: `[board] baud` in `espx.toml`, else espflash's default or `espflash.toml` | | `--monitor` | Open the serial monitor after flashing | | `-i`, `--interactive` | Let espflash ask which board to use when several are connected | | `--json` | Newline-delimited JSON events on stdout | | `-- ARGS` | Extra arguments for `cargo espflash flash`. With any, espx skips its own build step | See [Build and flash](https://www.espx.dev/docs/cli/build-and-flash). ## espx run Build, flash and open the serial monitor (`cargo espflash flash --release --monitor` in a terminal). ```sh espx run [--dir .] [--port P] [--until RE] [--expect RE]... [--reject RE]... [--timeout D] [--json] [-- ] ``` | Flag | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------- | | `--dir DIR` | Project directory. Default `.` | | `--port P` | Board: a port, a board id or a name. Default as for `flash` | | `--until RE` | Exit `0` once a monitor line matches this regex | | `--expect RE` | Exit `0` once lines matching each of these regexes have appeared, in order, one line each. Repeatable | | `--reject RE` | Exit `1` at once when a line matches this regex. Repeatable | | `--timeout D` | Stop monitoring after this long (`30s`, `2m`, `1h`) and exit `124` | | `--json` | Newline-delimited JSON events on stdout | | `-- ARGS` | Extra arguments for `cargo espflash flash`. With any, espx skips its own build step | With any of `--until`, `--expect`, `--reject`, `--timeout` or `--json`, or when stdin is not a terminal, espx flashes and reads the port itself. See [Scripts and CI](https://www.espx.dev/docs/cli/scripting). ## espx monitor Watch a board's serial output. In a terminal without other flags this is `espflash monitor` (`Ctrl+R` resets, `Ctrl+C` exits); otherwise espx reads the port itself and follows the board through resets. Works outside a project. ```sh espx monitor [--dir .] [--port P] [--baud B] [--until RE] [--expect RE]... [--reject RE]... [--timeout D] [--json] [--record PATH] [--input] [-- ] ``` | Flag | Meaning | | --------------- | ------------------------------------------------------------------------------------------------------------ | | `--dir DIR` | Project directory; its release binary, if built, decodes defmt and resolves backtraces. Default `.` | | `--port P` | Board: a port, a board id or a name. Default as for `flash` | | `--baud B` | Serial speed. Default 115200, or `MONITOR_BAUD` | | `--until RE` | Exit `0` once a line matches this regex | | `--expect RE` | Exit `0` once lines matching each of these regexes have appeared, in order. Repeatable | | `--reject RE` | Exit `1` at once when a line matches this regex. Repeatable | | `--timeout D` | Stop after this long (`30s`, `2m`) and exit `124` | | `--json` | Newline-delimited JSON events on stdout | | `--record PATH` | Write every event and the raw bytes to this file, for `espx replay` | | `--input` | Send each line typed on stdin to the board | | `-- ARGS` | Extra arguments for `espflash monitor`. An error together with the flags that make espx read the port itself | See [Monitor and replay](https://www.espx.dev/docs/cli/monitor). ## espx replay Play back a recording made with `monitor --record`, with its original timing. ```sh espx replay [--fast] [--until RE] [--expect RE]... [--reject RE]... [--timeout D] [--json] ``` | Argument or flag | Meaning | | ---------------- | -------------------------------------------------------------------------------------- | | `PATH` | The recording (newline-delimited JSON) | | `--fast` | Ignore the recorded timestamps and play back as fast as possible | | `--until RE` | Exit `0` once a line matches this regex | | `--expect RE` | Exit `0` once lines matching each of these regexes have appeared, in order. Repeatable | | `--reject RE` | Exit `1` at once when a line matches this regex. Repeatable | | `--timeout D` | Stop after this long and exit `124` | | `--json` | Newline-delimited JSON events on stdout | ## espx erase Erase the whole flash of a connected board with `espflash erase-flash`. This resets the board. ```sh espx erase [--port P] ``` | Flag | Meaning | | ---------- | ------------------------------------------------------ | | `--port P` | Serial port. Auto-detected when one board is connected | ## espx clean Remove build artifacts with `cargo clean`. ```sh espx clean [--dir .] ``` | Flag | Meaning | | ----------- | ------------------------------ | | `--dir DIR` | Project directory. Default `.` | ## espx devices List the serial ports with a dev board on them. ```sh espx devices [--all] [--probe] [--watch] [--json] ``` | Flag | Meaning | | --------- | --------------------------------------------------------------------------------------------------------- | | `--all` | List every serial port, not only known dev boards | | `--probe` | Identify the chip on each port with `espflash board-info`. This connects to and resets every board listed | | `--watch` | Keep running and report boards as they are plugged in and unplugged. Not with `--probe` or `--all` | | `--json` | One JSON document on stdout; with `--watch`, one event per line | See [Boards and ports](https://www.espx.dev/docs/cli/boards). ## espx info Show the chip, revision, crystal, flash size, features and MAC of a connected board with `espflash board-info`. This resets the board. ```sh espx info [--port P] [--json] ``` | Flag | Meaning | | ---------- | ------------------------------------------------------ | | `--port P` | Serial port. Auto-detected when one board is connected | | `--json` | One JSON document on stdout | ## espx chips List the supported chips with their architecture, Rust target and status. ```sh espx chips [--json] ``` | Flag | Meaning | | -------- | --------------------------- | | `--json` | One JSON document on stdout | See [Chips and boards](https://www.espx.dev/docs/reference/chips). ## espx boards List the supported dev board models: id, chip and name. ```sh espx boards [--json] ``` | Flag | Meaning | | -------- | --------------------------- | | `--json` | One JSON document on stdout | ## espx boards name Name a physical board in `~/.espx/boards.toml`. `espx devices` shows the name, and every `--port` flag accepts it. ```sh espx boards name ``` | Argument | Meaning | | -------- | --------------------------------------------- | | `BOARD` | The board's id, its port, or its current name | | `NAME` | The name: letters, digits, `-`, `_` and `.` | ## espx board Print one dev board model's LED, BOOT button and UART pins, USB ids and documentation link. ```sh espx board [--json] ``` | Argument or flag | Meaning | | ---------------- | --------------------------------------------------- | | `ID` | Board id from `espx boards`, such as `xiao-esp32c6` | | `--json` | One JSON document on stdout | ## espx deps Print the resolved versions of the esp-hal crate family from `Cargo.lock`. ```sh espx deps [--dir .] [--json] ``` | Flag | Meaning | | ----------- | ----------------------------------------------------- | | `--dir DIR` | Project directory. Default `.` | | `--json` | One JSON document on stdout, with each crate's source | ## espx context Print what an agent needs to write firmware here: chip, board pins, bound board, esp-hal version and features, the esp-hal examples link for the exact release, and attached boards. The same text `espx new` writes to `AGENTS.md`. ```sh espx context [--dir .] [--board B] [--json] ``` | Flag | Meaning | | ----------- | ----------------------------------------------------------------- | | `--dir DIR` | Project directory. Default `.` | | `--board B` | Board id (see `espx boards`) when the project does not record one | | `--json` | One JSON document on stdout | See [Agent context](https://www.espx.dev/docs/agents/context). ## espx doctor Check rustup, cargo, the tools, rust-src and the RISC-V targets of the `stable` toolchain, offline. The Xtensa rows are optional. ```sh espx doctor [--json] ``` | Flag | Meaning | | -------- | --------------------------- | | `--json` | One JSON document on stdout | ## espx env Print the shell `export` lines that put espx's tools (and, after an Xtensa setup, Espressif's fork) on the `PATH`. ```sh eval "$(espx env)" ``` ## espx agent Show what AI agents may do to boards in a project: the `[agent]` policy in `espx.toml`, with boards resolved to ids. ```sh espx agent [--dir .] [--json] ``` | Flag | Meaning | | ----------- | ------------------------------------------------------------------------------------------------- | | `--dir DIR` | Project directory. Default `.`. Also accepted by `agent set` and `agent allow` | | `--json` | One JSON document on stdout: the resulting policy. Also accepted by `agent set` and `agent allow` | See [Agent policy](https://www.espx.dev/docs/agents/policy). ## espx agent set Change the policy. Keys you leave out stay as they are, and comments in `espx.toml` are kept. Pass at least one flag. ```sh espx agent set [--boards B,..|--no-boards|--bound-board] [--flash on|off] [--erase on|off] ``` | Flag | Meaning | | ----------------- | ------------------------------------------------------------------------------- | | `--boards B,..` | The boards agents may touch, by id, name or port, comma-separated | | `--no-boards` | Let agents touch no board at all | | `--bound-board` | Let agents touch only the project's `[board] id` (the default without `boards`) | | `--flash on\|off` | Whether agents may flash the allowed boards | | `--erase on\|off` | Whether agents may erase the allowed boards | ## espx agent allow Make the smallest change that lets agents do one thing to one board. ```sh espx agent allow [--board B] ``` | Argument or flag | Meaning | | ---------------- | ----------------------------------------------------------------------------------- | | `ACTION` | `flash`, `erase` or `reset` | | `--board B` | The board, by id, name or port. Default: the project's board, else the one attached | ## espx log Show the agent audit log, `~/.espx/agent.log`: every tool call an agent made through espx. ```sh espx log [--json] [--tail N] ``` | Flag | Meaning | | ---------- | --------------------------- | | `--json` | One JSON document on stdout | | `--tail N` | Only the last N entries | ## espx mcp Serve the Model Context Protocol on stdio for AI agents. ```sh espx mcp ``` See [MCP server](https://www.espx.dev/docs/agents/mcp). ## espx mcp install Add espx to an MCP client: write its config file, or print the command that does. ```sh espx mcp install --client [--print] ``` | Flag | Meaning | | ------------ | --------------------------------------------------------------------------------------- | | `--client C` | The client to configure: `claude-code`, `claude-desktop`, `cursor`, `codex` or `vscode` | | `--print` | Print the config instead of writing it | ## espx update Update espx itself to the latest release, after checking its SHA-256 and its signature against the espx release key. Re-run `espx setup` to update the tools. ```sh espx update [--check] [--force] ``` | Flag | Meaning | | --------- | ------------------------------------------------- | | `--check` | Only report whether a newer release exists | | `--force` | Reinstall even when already on the latest release | > **Note** > > `update` replaces an `espx` that the [install script](https://www.espx.dev/docs/installation) put in `~/.espx/bin`. [Updating](https://www.espx.dev/docs/updating) has the details. It refuses the copy inside the desktop app, which the app updates itself, and a build that cargo installed: pull the repository and run `cargo install --path crates/espx-cli` again for that one. `--check` reports in every case. ## espx uninstall Remove what `espx setup` installed. Say what with flags, or choose with `-i`. ```sh espx uninstall [--home] [--xtensa] [--targets] [--shell] [--self] [--all] [-i] ``` | Flag | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------- | | `--home` | Remove `~/.espx`: the tools, the export file, the update cache, and everything else espx keeps there | | `--xtensa` | Remove Espressif's Rust fork: `espup uninstall`, `~/.espup`, the export file | | `--targets` | Remove the RISC-V Rust targets from rustup | | `--shell` | Remove the `eval "$(espx env)"` line from your shell config | | `--self` | Remove the espx binary itself | | `--all` | Everything above | | `-i`, `--interactive` | Ask about each item in the terminal | Without a flag and without `-i`, `uninstall` stops with `nothing_selected`.