id       = "espflash"
name     = "espflash"
homepage = "https://github.com/esp-rs/espflash"
description = "Serial flasher utility for Espressif SoCs and modules based on esptool.py."
executables   = ["espflash"]

[dotfiles]

# The official README documents these two global TOML files. Linux uses the
# literal $HOME/.config spelling; macOS and Windows use their platform-native
# application-data directories. The project-local espflash.toml is deliberately
# omitted because it lives beside the Cargo project, not in a user home.
# https://github.com/esp-rs/espflash/blob/main/espflash/README.md#configuration-files-location
paths = [
  "~/.config/espflash/espflash.toml",
  "~/.config/espflash/espflash_ports.toml",
  "[appData]/rs.esp.espflash/espflash.toml",
  "[appData]/rs.esp.espflash/espflash_ports.toml",
  "%APPDATA%/esp/espflash/espflash.toml",
  "%APPDATA%/esp/espflash/espflash_ports.toml",
]
exclude = []
secret = []

# The ports file is explicitly user-specific in the upstream documentation;
# a serial device name belongs to the machine rather than to the preference
# that should follow the user.
[[dotfiles.machine_lines]]
file  = [
  "~/.config/espflash/espflash_ports.toml",
  "[appData]/rs.esp.espflash/espflash_ports.toml",
  "%APPDATA%/esp/espflash/espflash_ports.toml",
]
match = { key_path = ["connection.serial"] }
scope = "backup"

[commands]
format = 1
label = "Flash ESP chips"
description = "Flash firmware to Espressif chips with espflash, inspect a connected board or list serial ports. Erase, partition-table, save-image and read-flash commands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
url = "https://github.com/esp-rs/espflash"
revision = "main 2026-10-27"
evidence = """
(Rendered from the clap definitions in espflash/src/cli/mod.rs and espflash/src/bin/espflash.rs)
Commands: board-info, flash, list-ports, monitor
-S, --skip-update-check    Do not check for updates
-p, --port <PORT>          Serial port connected to target device
-B, --baud <BAUD>          Baud rate at which to communicate with target device
-c, --chip <CHIP>          Target device
    --non-interactive      Avoids asking the user for interactions like selecting/resetting the device
    --no-stub              Do not use the RAM stub for loading
-M, --monitor              Open a serial monitor after flashing
    --no-verify            Don't verify the flash contents after flashing
    --erase-parts <LABELS> Erase partitions by label
    --partition-table <FILE> Input partition table
    --force                Skip compatibility checks (chip revision, etc.). Use with caution!
-a, --list-all-ports       List all available serial ports, instead of just those likely to be development boards.
-n, --name-only            Only print the name of the ports and nothing else.
espflash flash --baud=921600 --monitor /dev/ttyUSB0
Flash an application in ELF format to a connected target device
Print information about a connected target device
List available serial ports.
"""

[[commands.field]]
id = "skip_update_check"
label = "Skip update check"
type = "boolean"
option = ["--skip-update-check", "-S"]
sources = ["help"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["skip_update_check"]

[[commands.subcommand]]
path = ["flash"]
label = "Flash an ELF image"
description = "Flash an ELF application to the connected device. Format, partition and monitor tuning options are left out."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://github.com/esp-rs/espflash"
revision = "main 2026-10-27"
evidence = """
(Rendered from the clap definitions in espflash/src/cli/mod.rs and espflash/src/bin/espflash.rs)
Commands: board-info, flash, list-ports, monitor
-S, --skip-update-check    Do not check for updates
-p, --port <PORT>          Serial port connected to target device
-B, --baud <BAUD>          Baud rate at which to communicate with target device
-c, --chip <CHIP>          Target device
    --non-interactive      Avoids asking the user for interactions like selecting/resetting the device
    --no-stub              Do not use the RAM stub for loading
-M, --monitor              Open a serial monitor after flashing
    --no-verify            Don't verify the flash contents after flashing
    --erase-parts <LABELS> Erase partitions by label
    --partition-table <FILE> Input partition table
    --force                Skip compatibility checks (chip revision, etc.). Use with caution!
-a, --list-all-ports       List all available serial ports, instead of just those likely to be development boards.
-n, --name-only            Only print the name of the ports and nothing else.
espflash flash --baud=921600 --monitor /dev/ttyUSB0
Flash an application in ELF format to a connected target device
Print information about a connected target device
List available serial ports.
"""

[[commands.subcommand.field]]
id = "image"
label = "ELF image"
type = "path"
position = 0
path = { kind = "file", role = "input", must_exist = true }
sources = ["help"]

[[commands.subcommand.field]]
id = "port"
label = "Serial port"
description = "Leave empty to auto-detect a connected board."
type = "string"
option = ["--port", "-p"]
sources = ["help"]

[[commands.subcommand.field]]
id = "baud"
label = "Baud rate"
type = "integer"
option = ["--baud", "-B"]
min = 1
sources = ["help"]

[[commands.subcommand.field]]
id = "chip"
label = "Chip"
description = "Target chip; usually auto-detected."
type = "string"
option = ["--chip", "-c"]
suggestions = [{ value = "esp32", label = "ESP32" }, { value = "esp32c3", label = "ESP32-C3" }, { value = "esp32s3", label = "ESP32-S3" }]
sources = ["help"]

[[commands.subcommand.field]]
id = "non_interactive"
label = "Non-interactive"
type = "boolean"
option = ["--non-interactive"]
sources = ["help"]

[[commands.subcommand.field]]
id = "monitor"
label = "Open monitor after flashing"
type = "boolean"
option = ["--monitor", "-M"]
sources = ["help"]

[[commands.subcommand.field]]
id = "no_verify"
label = "Skip verification"
type = "boolean"
option = ["--no-verify"]
sources = ["help"]

[[commands.subcommand.field]]
id = "no_stub"
label = "No RAM stub"
type = "boolean"
option = ["--no-stub"]
sources = ["help"]

[[commands.subcommand.field]]
id = "erase_parts"
label = "Erase partitions first"
description = "Comma-separated partition labels to erase."
type = "string"
option = ["--erase-parts"]
effect = "delete"
sources = ["help"]

[[commands.subcommand.field]]
id = "partition_table"
label = "Partition table"
type = "path"
option = ["--partition-table"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["help"]

[[commands.subcommand.task]]
id = "flash"
label = "Flash and monitor"
fields = ["image", "port", "baud", "monitor"]
required = ["image"]
set = { monitor = [true] }

[[commands.subcommand.task]]
id = "flash-only"
label = "Flash only"
fields = ["image", "port", "baud", "chip"]
required = ["image"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["image", "port", "baud", "monitor"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["chip", "non_interactive", "no_verify", "no_stub", "erase_parts", "partition_table"]

[[commands.subcommand]]
path = ["board-info"]
label = "Show board info"
description = "Print chip type, flash size, features and MAC address of the connected device."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://github.com/esp-rs/espflash"
revision = "main 2026-10-27"
evidence = """
(Rendered from the clap definitions in espflash/src/cli/mod.rs and espflash/src/bin/espflash.rs)
Commands: board-info, flash, list-ports, monitor
-S, --skip-update-check    Do not check for updates
-p, --port <PORT>          Serial port connected to target device
-B, --baud <BAUD>          Baud rate at which to communicate with target device
-c, --chip <CHIP>          Target device
    --non-interactive      Avoids asking the user for interactions like selecting/resetting the device
    --no-stub              Do not use the RAM stub for loading
-M, --monitor              Open a serial monitor after flashing
    --no-verify            Don't verify the flash contents after flashing
    --erase-parts <LABELS> Erase partitions by label
    --partition-table <FILE> Input partition table
    --force                Skip compatibility checks (chip revision, etc.). Use with caution!
-a, --list-all-ports       List all available serial ports, instead of just those likely to be development boards.
-n, --name-only            Only print the name of the ports and nothing else.
espflash flash --baud=921600 --monitor /dev/ttyUSB0
Flash an application in ELF format to a connected target device
Print information about a connected target device
List available serial ports.
"""

[[commands.subcommand.field]]
id = "port"
label = "Serial port"
description = "Leave empty to auto-detect a connected board."
type = "string"
option = ["--port", "-p"]
sources = ["help"]

[[commands.subcommand.field]]
id = "baud"
label = "Baud rate"
type = "integer"
option = ["--baud", "-B"]
min = 1
sources = ["help"]

[[commands.subcommand.field]]
id = "chip"
label = "Chip"
description = "Target chip; usually auto-detected."
type = "string"
option = ["--chip", "-c"]
suggestions = [{ value = "esp32", label = "ESP32" }, { value = "esp32c3", label = "ESP32-C3" }, { value = "esp32s3", label = "ESP32-S3" }]
sources = ["help"]

[[commands.subcommand.field]]
id = "non_interactive"
label = "Non-interactive"
type = "boolean"
option = ["--non-interactive"]
sources = ["help"]

[[commands.subcommand.task]]
id = "info"
label = "Show board info"
fields = ["port", "baud", "chip"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["port", "baud", "chip", "non_interactive"]

[[commands.subcommand]]
path = ["list-ports"]
label = "List serial ports"
description = "List serial ports, by default only those used by development boards."

[[commands.subcommand.source]]
id = "help"
kind = "help"
url = "https://github.com/esp-rs/espflash"
revision = "main 2026-10-27"
evidence = """
(Rendered from the clap definitions in espflash/src/cli/mod.rs and espflash/src/bin/espflash.rs)
Commands: board-info, flash, list-ports, monitor
-S, --skip-update-check    Do not check for updates
-p, --port <PORT>          Serial port connected to target device
-B, --baud <BAUD>          Baud rate at which to communicate with target device
-c, --chip <CHIP>          Target device
    --non-interactive      Avoids asking the user for interactions like selecting/resetting the device
    --no-stub              Do not use the RAM stub for loading
-M, --monitor              Open a serial monitor after flashing
    --no-verify            Don't verify the flash contents after flashing
    --erase-parts <LABELS> Erase partitions by label
    --partition-table <FILE> Input partition table
    --force                Skip compatibility checks (chip revision, etc.). Use with caution!
-a, --list-all-ports       List all available serial ports, instead of just those likely to be development boards.
-n, --name-only            Only print the name of the ports and nothing else.
espflash flash --baud=921600 --monitor /dev/ttyUSB0
Flash an application in ELF format to a connected target device
Print information about a connected target device
List available serial ports.
"""

[[commands.subcommand.field]]
id = "all"
label = "Include all ports"
type = "boolean"
option = ["--list-all-ports", "-a"]
sources = ["help"]

[[commands.subcommand.field]]
id = "name_only"
label = "Names only"
type = "boolean"
option = ["--name-only", "-n"]
sources = ["help"]

[[commands.subcommand.task]]
id = "list"
label = "List ports"
fields = ["all", "name_only"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["all", "name_only"]