CLI Reference

The embedr command is the firmware toolchain behind the desktop app's Compile, Flash and library features. It ships with the app: in the editor's Terminal tab, embedr (and the hardware tool pcb) are already on the path. See Terminal and setup.

Every command that works on a project looks for embedr.yaml in the current folder. Pass --path <folder> to work on another project.

Global options

embedr --version
embedr --format json <command> ...
embedr -f json <command> ...

Option	Meaning
--version	Print the CLI version.
--format, -f text|json	Output format. Default text. Put it before the command name.

Use --format json in scripts and CI. Note that -f means something else after some commands (boards -f filters, init -f sets the framework, devices -f filters).

Commands at a glance

Command	Purpose
embedr init	Create a project.
embedr boards	List board presets.
embedr compile	Build firmware.
embedr upload	Flash firmware to a device.
embedr run	Build and flash, optionally then monitor.
embedr monitor	Serial monitor.
embedr devices	List connected serial devices.
embedr debug	Start a debug server or GDB.
embedr clean	Remove build output.
embedr validate	Check project structure and components.
embedr lib ...	PlatformIO libraries.
embedr target-config, set-target-config, select-target	Read and persist target settings.
embedr manifest inspect, manifest discover	Inspect embedr.yaml runtime metadata.
embedr pcb ...	The project's pcb/ hardware workspace.
embedr search, add, remove, list	Hardware component references in embedr.yaml.
embedr agent	Run the desktop app's agent from the terminal.

Create a project

embedr init                          # initialise the current folder (Arduino Uno)
embedr init --name my-project        # current folder, explicit project name
embedr init my-project               # new folder ./my-project
embedr init my-project -b esp32      # ESP32, Arduino framework
embedr init my-project -b esp32-idf  # ESP32, ESP-IDF
embedr init my-project -b pico       # Raspberry Pi Pico

Option	Meaning
NAME (argument)	Create a new folder with this name. Omit to initialise the current folder.
--name	Project name when initialising the current folder (or --path). Cannot be combined with NAME.
--board, -b	Board preset. Default uno. Run embedr boards for the list.
--platform, -p	PlatformIO platform, overriding the preset.
--framework, -f	Framework override (arduino, espidf, stm32cube...).
--description, -d	Project description.
--path	Parent folder for a named project, or the project folder when NAME is omitted.

It creates:

my-project/
├── embedr.yaml
├── platformio.ini
├── src/
│   └── main.cpp      # or main.c, depending on the framework
├── lib/
└── .gitignore

An unknown board preset fails and suggests similar ones. Initialising a folder that already has embedr.yaml, or creating a folder that already exists, fails.

Boards

embedr boards
embedr boards --all
embedr boards --filter esp32
embedr boards --category stm32
embedr boards --limit 20
embedr boards --sync

Option	Meaning
--filter, -f	Filter by name, platform or category.
--all, -a	Show every board, not just the popular ones.
--category, -c	esp, arduino, stm32, rp2040, teensy, nordic or samd.
--limit, -l	Maximum number of boards.
--sync, -s	Refresh the board index from the remote registry.

Build

embedr compile
embedr compile -e esp32dev
embedr compile --clean
embedr compile --verbose
embedr compile --monitor-speed 115200 --upload-speed 921600

Option	Meaning
--environment, -e	Environment from platformio.ini.
--clean, -c	Clean before building.
--verbose, -v	Verbose build output.
--upload-protocol	Upload protocol override.
--upload-speed	Upload speed override.
--monitor-speed	Serial monitor speed override.
--debug-tool	Debug tool override.
--path	Project folder.

For projects with manifest_version: 1, the four override options are saved to the project, not just used once.

The first build of an environment downloads its toolchain and may take up to 20 minutes; later builds are limited to 10. A build that runs out of time reports Build timed out after … with the last part of its output.

Upload and run

embedr upload                       # auto-detect the port
embedr upload -p /dev/cu.usbserial-0001
embedr upload -p COM3
embedr upload --select              # choose interactively when several boards are connected

embedr run                          # build and upload
embedr run -m                       # build, upload, then open the serial monitor
embedr run -p /dev/ttyUSB0

upload options:

Option	Meaning
--port, -p	Serial port. Auto-detected if omitted.
--select, -s	Pick the device interactively when more than one is connected.
--environment, -e	Environment.
--verbose, -v	Verbose output.
--upload-protocol, --upload-speed, --monitor-speed, --debug-tool	Same as compile.
--path	Project folder.

run options: --port/-p, --environment/-e, --verbose/-v, --monitor/-m (open the serial monitor after uploading) and --path.

Monitor and devices

embedr devices
embedr devices -f USB
embedr devices -f "Silicon Labs"
embedr devices --watch
embedr --format json devices

embedr monitor
embedr monitor -p /dev/ttyUSB0 -b 9600

devices option	Meaning
--filter, -f	Filter by name, port or vendor (USB, ttyACM, Silicon Labs).
--watch, -w	Keep watching for devices being plugged in or removed. Ctrl+C stops.

monitor option	Meaning
--port, -p	Serial port. Auto-detected if omitted.
--baud, -b	Baud rate. Defaults to the project's monitor speed.
--environment, -e	Environment.
--path	Project folder.

Press Ctrl+C to leave the monitor.

Debug

embedr debug              # debug server on port 3333
embedr debug -i gdb       # interactive GDB
embedr debug -p 4444      # custom server port

Option	Meaning
--interface, -i server|gdb	Start a debug server (default) or an interactive GDB session.
--port, -p	Debug server port. Default 3333.
--environment, -e	Environment.
--path	Project folder.

Needs a debug probe (ESP-Prog, J-Link, ST-Link...) and a build with debug symbols.

Clean and validate

embedr clean
embedr validate

clean removes build output. validate checks the project structure and its component references. Both take --path.

Libraries

embedr lib search "neopixel"
embedr lib search dht --limit 5
embedr lib install "Adafruit NeoPixel"
embedr lib install "DHT sensor library" --version 1.4.4
embedr lib list
embedr lib uninstall FastLED
embedr lib update

Command	Options	What it does
lib search QUERY	--limit, -l (default 20)	Search the PlatformIO registry.
lib install LIBRARY	--version, -v; --path	Install and add to the project's declared libraries.
lib list	--path	Show declared and installed libraries.
lib uninstall LIBRARY	--path	Remove from the declared list and uninstall.
lib update	--path	Update all libraries.

See Dependencies and libraries for where the list is stored.

Target settings

embedr target-config
embedr target-config --target esp32 -e esp32dev
embedr set-target-config --monitor-speed 115200 --upload-speed 921600
embedr set-target-config --reset-defaults
embedr select-target --target esp32-s3

Command	What it does
target-config	Print the supported target settings (upload protocol and speed, monitor speed, debug tool) and their current values.
set-target-config	Save settings to the project. --reset-defaults resets every supported setting before applying the ones you pass.
select-target	Switch the project to a board preset and save the matching embedr.yaml and platformio.ini state. --target is required.

Shared options: --target, --environment/-e, --path. set-target-config and select-target also take --upload-protocol, --upload-speed, --monitor-speed and --debug-tool; select-target takes --manifest-target-id to store a stable target id in embedr.yaml.

The toolbar's target picker uses the same settings. See Targets and environments.

Manifest

embedr manifest inspect
embedr manifest inspect -e esp32dev
embedr manifest discover
embedr manifest discover --write

Command	Options	What it does
manifest inspect	--environment/-e, --path	Print the project's manifest as Embedr resolves it, for one environment.
manifest discover	--write, --path	Look at an existing project (Zephyr west.yml/prj.conf, CMake, Makefile, Cargo, package.json, src/, include/) and suggest how it builds. --write saves the suggestions to embedr.yaml.

See Project manifest.

PCB workspace

These commands work on the project's pcb/ folder.

embedr pcb init
embedr pcb status
embedr pcb build
embedr pcb test
embedr pcb layout
embedr pcb layout --check
embedr pcb layout --no-open
embedr pcb layout --sync-footprints
embedr pcb open
embedr pcb fmt

Command	What it does
pcb init	Create the pcb/ workspace. Reports which files it created and which already existed.
pcb status	Show the hardware toolchain, the workspace and the main board.
pcb build	Build the Zener source.
pcb test	Run the source's checks.
pcb layout	Generate or update the KiCad board. --check only checks, --no-open does not open KiCad afterwards, --sync-footprints reloads footprints from source while keeping placement and routing.
pcb open	Open the board in KiCad.
pcb fmt	Format the Zener source.

All take --path; all but init and status also take --file <file.zen> to pick a source file. Everything except init and status needs embedr pcb init first.

The app and agent have many more hardware actions (placement, routing, checks, exports, simulation). See Schematics and PCB and Placement and routing.

Components

These manage hardware part references in embedr.yaml, not firmware libraries.

embedr search led
embedr search --category Sensors
embedr search -r
embedr add led-5mm
embedr add led-5mm --instance status_led
embedr remove led-5mm --instance status_led
embedr list

Command	Options
search [QUERY]	--category/-c, --limit/-l (default 20), --rebuild-index/-r. With no query, lists everything.
add COMPONENT_ID	--instance/-i (for several of the same part), --path
remove COMPONENT_ID	--instance/-i, --path
list	Lists the components in the current project.

For the searchable part library with symbols, footprints and datasheets, see Component library.

Desktop agent

embedr agent sends requests to the same agent that runs in the desktop app, using your signed-in account, models, approvals and chat history. The desktop app must be open and signed in; otherwise it fails with Embedr Desktop is not available. Open the desktop app, sign in, and retry.

embedr agent "build the firmware and fix any errors"   # one request
embedr agent                                           # interactive: type requests at the embedr> prompt
embedr agent --plan "plan a migration to the new sensor"
embedr agent --resume <thread-id>                      # continue a desktop chat thread
embedr agent --json "inspect the project"

Option	Meaning
PROMPT (argument)	One request. Omit for an interactive session (needs an interactive terminal).
--project	Project folder. Default: the current folder.
--resume	Continue an existing chat thread by its id. Without it each session starts a new thread.
--model	Model to use. Default gpt-6-sol.
--context-window	The model's context size in tokens, if known.
--plan	Use read-only Plan Mode.
--json	Write events as JSON Lines.
--yes	Approve every tool request in this session. Use only in controlled environments.
--verbose-tools	Print full tool results to stderr.

Without --yes, tool approvals are asked in the terminal; in a non-interactive session they are declined. A one-shot request that ends in an error exits with status 1. Ctrl+D leaves the interactive prompt.

Scripting

Pass everything explicitly so scripts do not depend on the app's toolbar state:

embedr --format json validate --path ./robot
embedr --format json compile --path ./robot -e esp32dev
embedr --format json upload --path ./robot -e esp32dev -p /dev/ttyUSB0