Remove exit() call for python module cli usage (ESPTOOL-1125)

[belezyakov]

Is your feature request related to a problem?

While migrating from 4.x.x to 5.x.x esptool version for using as python module with basic cli integration (e.g. calling esptool.main(), espefuse.main()) I have noticed not obvious change that such usage now leads to script exiting after any esptool main(cmd) with exit() calling. So there is no bare option to use a chain of esptool cmd calls or some post-esptool call logic. To achieve that I am catching SystemExit exception for each esptool command call and just pass it on script side.

Describe the solution you'd like

No response

Describe alternatives you've considered

No response

Additional context

No response

[github-actions]

Hi @belezyakov! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for raising this issue regarding the use of exit() in the CLI entry points (esptool.main(), espefuse.main(), etc.) when using esptool as a Python module in v5.x.x.

Background

With the release of esptool v5, the recommended way to use esptool programmatically is through the new public API provided in the esptool.cmds module, rather than invoking the CLI entry points (main() functions). The new API is designed for direct integration into Python scripts and supports chaining operations, structured workflows, and custom logging, without the side effects of process termination that occur with CLI-style usage. This is a significant change from v4.x.x, where CLI entry points were sometimes used for scripting purposes, despite not being intended for that use case in the long term.

Current Behavior

As you observed, calling esptool.main() or similar CLI entry points in v5 will result in the script exiting after execution, due to the use of exit() (or sys.exit()). This is standard for CLI tools but not suitable for programmatic use, as it prevents chaining commands or running additional logic after the call. The only workaround is to catch the SystemExit exception, which is not ideal.

Recommended Solution

For programmatic use and chaining operations, it is strongly recommended to migrate to the new public API in esptool.cmds. This API is specifically designed for use in Python scripts and does not call exit(), allowing you to chain commands and add post-processing logic as needed. Here is an example of the new approach:

from esptool.cmds import (
    detect_chip, run_stub, attach_flash, flash_id,
    read_flash, erase_flash, write_flash, verify_flash, reset_chip
)

PORT = "/dev/ttyUSB0"
BOOTLOADER = "bootloader.bin"
FIRMWARE = "firmware.bin"

with detect_chip(PORT) as esp:
    esp = run_stub(esp)
    attach_flash(esp)
    flash_id(esp)
    read_flash(esp, 0x0, 0x8000, "bl_backup.bin")
    erase_flash(esp)
    write_flash(esp, [(0, BOOTLOADER), (0x10000, FIRMWARE)])
    verify_flash(esp, [(0, BOOTLOADER), (0x10000, FIRMWARE)])
    reset_chip(esp, "hard_reset")

This approach avoids the CLI entry points entirely and is the officially supported method for scripting and integration as of v5.x.x. For more details and examples, see the esptool v5 migration guide and the developer blog post.

Regarding the Feature Request

The use of exit() in the CLI entry points is intentional for command-line usage. There is no indication in the official documentation that this behavior will be changed, as the new public API is the recommended and supported way for programmatic use. If you need to avoid process termination, please migrate your scripts to use the new API.

If you have a specific use case that cannot be addressed by the new API, you may want to describe it in more detail so the maintainers can consider whether further changes are warranted.

---

Summary:

• The exit() call in CLI entry points is expected for CLI tools.
• For scripting and chaining, use the new esptool.cmds API, which does not call exit().
• See the migration guide and developer blog for details and examples.

If you need further help migrating to the new API, please let us know!

[dobairoland]

Hi @belezyakov. Please see and try d8ae230. It has already been released in v5.1.dev1.

[belezyakov]

Hi @belezyakov. Please see and try d8ae230. It has already been released in v5.1.dev1.

Great, hope it will be presented in new tool release.