Back to LearnTuyaOpen SDK

tos.py command reference

tos.py is the one CLI for configuring, building, flashing, and monitoring TuyaOpen projects. Each subcommand below shows its signature, a real example, and when to use it.

IntermediateReferenceCLI

What tos.py is

After activating TuyaOpen, tos.py is on your PATH. It wraps project configuration, the build system, flashing, and log monitoring behind a small set of subcommands. Run tos.py --help any time to see the list.

Run every command from inside an application project directory — config, build, clean, flash, and monitor all require it.
The first build downloads the toolchain into platform/ — expect it to be slower than subsequent builds.
Re-activate tos.py each time you open a new terminal (. ./export.sh on Linux/Mac, .\export.ps1 on Windows).

Setup & environment

tos.py version

❯ tos.py version
[INFO]: v1.3.0-23-g6bcb5aa

See the current tag-commit. [Unknown version] means the repo has no tags (common in forks).

tos.py check

❯ tos.py check
[INFO]: [git] (2.43.0 >= 2.0.0) is ok.
...

After install or pull — validates git/cmake/make/ninja versions and runs git submodule update --init.

Configure the project

These pick or tune the board configuration. The choice is written to app_default.config; both choice and menu deep-clean first because they may switch toolchain.

tos.py config choice

❯ tos.py config choice
1. T5AI.config
2. ESP32.config
...
Choice config file:

Pick a verified board config for the current project.

tos.py config menu

tos.py config menu   # opens the visual Kconfig menu

Tune Kconfig options interactively; save from inside the menu.

tos.py config save

❯ tos.py config save
Input save config name:

Save your current menu-tuned config as a named solidified config in the project config/ directory.

Build & clean

tos.py build [-v]

❯ tos.py build
...
[INFO]: ******* Build Success ********

Compile the project into a flashable bin in .build/bin. -v for verbose output.

tos.py clean [-f]

❯ tos.py clean -f
[INFO]: Fullclean success.

Clear the build cache. -f deep-cleans by deleting .build after ninja clean.

Flash & monitor

tos.py flash [-p PORT] [-b BAUD]

❯ tos.py flash
...
[INFO]: Flash write success.

Write the built bin to the device. Omit -p to pick the port from a list.

tos.py monitor [-p PORT] [-b BAUD]

❯ tos.py monitor
[INFO]: Open Monitor. (Quit: Ctrl+c)

Stream the device serial log. Quit with Ctrl+C then Enter. Also used to write the auth code.

Workflow & scaffolding

tos.py update

tos.py update

After git pull/git checkout on the main repo — switches dependencies to the commits in platform/platform_config.yaml.

tos.py new [--framework base|arduino]

tos.py new  # prompts for project name, copies a template

Scaffold a new user application from tools/app_template/ (base or arduino framework).

tos.py dev bac [-d DIST] [-o LOGDIR]

tos.py dev bac  # build every config in config/ (or boards/)

Build-all-config: iterate every .config, full-clean between builds, optionally copy bins to a dist folder.

tos.py idf <idf.py subcommand> [--idf-flags=...]

tos.py idf menuconfig
tos.py idf fullclean

ESP32 only. Run idf.py commands against the ESP32 platform checkout. Requires an ESP32 config.

Global flags

These work on any subcommand:

-d / --debug — show debug-level execution logs (e.g. tos.py -d version).
-h / --help — show help for the command (e.g. tos.py flash -h).

Full tos.py docs →