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`	Install the esp-rs tools and Rust targets
`new`	Create a project with esp-generate
`build`	`cargo build --release` with a size check
`flash`	Build and `cargo espflash flash --release`
`run`	Build, flash and monitor
`monitor`	Watch a board's serial output
`replay`	Play back a recording
`erase`	Erase a board's whole flash
`clean`	`cargo clean`
`devices`	List attached boards
`info`	Read a board's chip, flash size and MAC
`chips`	List supported chips
`boards`	List known dev boards, or name an attached one
`board`	Print one dev board's pins
`deps`	Resolved esp-hal crate versions
`context`	What an agent needs to write firmware here
`doctor`	Check the toolchain, offline
`env`	Shell exports for the tools
`agent`	Show or change what AI agents may do
`log`	The agent audit log
`mcp`	Serve MCP, or add espx to an MCP client
`update`	Update espx to the latest signed release (the app's copy updates with the app)
`uninstall`	Remove what `setup` installed

espx setup

Install the esp-rs tools into ~/.espx/bin and the Rust targets for your chips. Idempotent.

espx setup [--chip <list>|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 and Xtensa chips.

espx new

Create a bare-metal Rust project for a chip with esp-generate, plus a README and AGENTS.md.

espx new <name> [--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.

espx build

Build the project with cargo build --release, then report the image and RAM size and check the image fits the app partition.

espx build [--dir .] [--json] [-- <cargo args>]

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.

espx flash [--dir .] [--port P] [--baud B] [--monitor] [-i] [--json] [-- <args>]

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.

espx run

Build, flash and open the serial monitor (cargo espflash flash --release --monitor in a terminal).

espx run [--dir .] [--port P] [--until RE] [--expect RE]... [--reject RE]... [--timeout D] [--json] [-- <args>]

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.

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.

espx monitor [--dir .] [--port P] [--baud B] [--until RE] [--expect RE]... [--reject RE]... [--timeout D] [--json] [--record PATH] [--input] [-- <args>]

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.

espx replay

Play back a recording made with monitor --record, with its original timing.

espx replay <PATH> [--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.

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.

espx clean [--dir .]

Flag	Meaning
`--dir DIR`	Project directory. Default `.`

espx devices

List the serial ports with a dev board on them.

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.

espx info

Show the chip, revision, crystal, flash size, features and MAC of a connected board with espflash board-info. This resets the board.

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.

espx chips [--json]

Flag	Meaning
`--json`	One JSON document on stdout

See Chips and boards.

espx boards

List the supported dev board models: id, chip and name.

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.

espx boards name <BOARD> <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.

espx board <ID> [--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.

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.

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.

espx doctor

Check rustup, cargo, the tools, rust-src and the RISC-V targets of the stable toolchain, offline. The Xtensa rows are optional.

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.

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.

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.

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.

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.

espx agent allow <flash|erase|reset> [--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.

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.

espx mcp

See MCP server.

espx mcp install

Add espx to an MCP client: write its config file, or print the command that does.

espx mcp install --client <claude-code|claude-desktop|cursor|codex|vscode> [--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.

espx update [--check] [--force]

Flag	Meaning
`--check`	Only report whether a newer release exists
`--force`	Reinstall even when already on the latest release

update replaces an espx that the install script put in ~/.espx/bin. 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.

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.