CLI Reference

Note

All CLI options could be defined in the config file. For more information, please refer to the Config File Reference.

Tools for building ESP-IDF related apps. Some CLI options can be expanded by the following placeholders, like “–work-dir”, “–build-dir”, etc.: - @t: would be replaced by the target chip type - @w: would be replaced by the wildcard, usually the sdkconfig - @n: would be replaced by the app name - @f: would be replaced by the escaped app path (replaced “/” to “_”) - @v: Would be replaced by the ESP-IDF version like 5_3_0 - @i: would be replaced by the build index (only available in build command) - @p: would be replaced by the parallel index (only available in build command)

usage: idf-build-apps [-h] {find,build,completions,dump-manifest-sha} ...

Positional Arguments

action: Possible choices: find, build, completions, dump-manifest-sha

Sub-commands

find

Find the buildable applications in the given path or paths for specified chips. –path and –target options must be provided. By default, print the found apps in stdout. To find apps for all chips use the –target option with the all argument.

idf-build-apps find [-h] [--config-file CONFIG_FILE] [--verbose]
                    [--log-file LOG_FILE] [--no-color]
                    [--manifest-file MANIFEST_FILE [MANIFEST_FILE ...]]
                    [--manifest-files MANIFEST_FILES [MANIFEST_FILES ...]]
                    [--manifest-filepatterns MANIFEST_FILEPATTERNS [MANIFEST_FILEPATTERNS ...]]
                    [--manifest-rootpath MANIFEST_ROOTPATH]
                    [--modified-components MODIFIED_COMPONENTS]
                    [--modified-files MODIFIED_FILES]
                    [--ignore-app-dependencies-components IGNORE_APP_DEPENDENCIES_COMPONENTS]
                    [--deactivate-dependency-driven-build-by-components DEACTIVATE_DEPENDENCY_DRIVEN_BUILD_BY_COMPONENTS]
                    [--ignore-app-dependencies-filepatterns IGNORE_APP_DEPENDENCIES_FILEPATTERNS]
                    [--deactivate-dependency-driven-build-by-filepatterns DEACTIVATE_DEPENDENCY_DRIVEN_BUILD_BY_FILEPATTERNS]
                    [--check-manifest-rules]
                    [--compare-manifest-sha-filepath COMPARE_MANIFEST_SHA_FILEPATH]
                    [--paths [PATHS [PATHS ...]]] [--target TARGET]
                    [--build-system {cmake,make}] [--recursive]
                    [--exclude EXCLUDE [EXCLUDE ...]] [--work-dir WORK_DIR]
                    [--build-dir BUILD_DIR] [--build-log BUILD_LOG]
                    [--build-log-filename BUILD_LOG_FILENAME]
                    [--size-file SIZE_FILE]
                    [--size-json-filename SIZE_JSON_FILENAME]
                    [--config CONFIG [CONFIG ...]]
                    [--config-rules CONFIG_RULES [CONFIG_RULES ...]]
                    [--override-sdkconfig-items OVERRIDE_SDKCONFIG_ITEMS]
                    [--override-sdkconfig-files OVERRIDE_SDKCONFIG_FILES]
                    [--sdkconfig-defaults SDKCONFIG_DEFAULTS]
                    [--check-warnings]
                    [--default-build-targets DEFAULT_BUILD_TARGETS [DEFAULT_BUILD_TARGETS ...]]
                    [--enable-preview-targets] [--include-skipped-apps]
                    [--include-disabled-apps] [--include-all-apps]
                    [--output OUTPUT] [--output-format {raw,json}]

Named Arguments

--config-file

Path to the config file

--verbose, -v

Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

--log-file

Path to the log file, if not specified logs will be printed to stderr

--no-color

Disable colored output

--manifest-file

[Deprecated] Use –manifest-files instead

--manifest-files

Path to the manifest files which contains the build test rules of the apps

--manifest-filepatterns

space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

--manifest-rootpath

Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

--modified-components

semicolon-separated list of modified components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--modified-files

semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--ignore-app-dependencies-components, -ic

[Deprecated] Use –deactivate-dependency-driven-build-by-components instead

--deactivate-dependency-driven-build-by-components, -dc

semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified together with –modified-components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--ignore-app-dependencies-filepatterns, -if

[Deprecated] Use –deactivate-dependency-driven-build-by-filepatterns instead

--deactivate-dependency-driven-build-by-filepatterns, -df

semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified together with –modified-files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--check-manifest-rules

Check if all folders defined in the manifest files exist. Fail if not

--compare-manifest-sha-filepath

Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

--paths, -p

Paths to the directories containing the apps. By default set to the current directory

--target, -t

Filter the apps by target. By default set to “all”

--build-system

Possible choices: cmake, make

Filter the apps by build system. By default set to “cmake”

--recursive

Search for apps recursively under the specified paths

--exclude

Ignore the specified directories while searching recursively

--work-dir

Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

--build-dir

Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

--build-log

[Deprecated] Use –build-log-filename instead

--build-log-filename

Log filename under the build directory instead of stdout. Can expand placeholders

--size-file

[Deprecated] Use –size-json-filename instead

--size-json-filename

idf.py size output file under the build directory when specified. Can expand placeholders

--config

[Deprecated] Use –config-rules instead

--config-rules

Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

--override-sdkconfig-items

A comma-separated list of key=value pairs to override the sdkconfig items

--override-sdkconfig-files

A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

--sdkconfig-defaults

A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

--check-warnings

Check for warnings in the build output. Fail if any warnings are found

--default-build-targets

space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

--enable-preview-targets

When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

--include-skipped-apps

Include the skipped apps in the output, together with the enabled ones

--include-disabled-apps

Include the disabled apps in the output, together with the enabled ones

--include-all-apps

Include skipped, and disabled apps in the output, together with the enabled ones

--output, -o

Record the found apps to the specified file instead of stdout

--output-format

Possible choices: raw, json

Output format of the found apps. In “raw” format, each line is a json string serialized from the app model. In “json” format, the output is a json list of the serialized app models

build

Build the application in the given path or paths for specified chips. –path and –target options must be provided.

idf-build-apps build [-h] [--config-file CONFIG_FILE] [--verbose]
                     [--log-file LOG_FILE] [--no-color]
                     [--manifest-file MANIFEST_FILE [MANIFEST_FILE ...]]
                     [--manifest-files MANIFEST_FILES [MANIFEST_FILES ...]]
                     [--manifest-filepatterns MANIFEST_FILEPATTERNS [MANIFEST_FILEPATTERNS ...]]
                     [--manifest-rootpath MANIFEST_ROOTPATH]
                     [--modified-components MODIFIED_COMPONENTS]
                     [--modified-files MODIFIED_FILES]
                     [--ignore-app-dependencies-components IGNORE_APP_DEPENDENCIES_COMPONENTS]
                     [--deactivate-dependency-driven-build-by-components DEACTIVATE_DEPENDENCY_DRIVEN_BUILD_BY_COMPONENTS]
                     [--ignore-app-dependencies-filepatterns IGNORE_APP_DEPENDENCIES_FILEPATTERNS]
                     [--deactivate-dependency-driven-build-by-filepatterns DEACTIVATE_DEPENDENCY_DRIVEN_BUILD_BY_FILEPATTERNS]
                     [--check-manifest-rules]
                     [--compare-manifest-sha-filepath COMPARE_MANIFEST_SHA_FILEPATH]
                     [--paths [PATHS [PATHS ...]]] [--target TARGET]
                     [--build-system {cmake,make}] [--recursive]
                     [--exclude EXCLUDE [EXCLUDE ...]] [--work-dir WORK_DIR]
                     [--build-dir BUILD_DIR] [--build-log BUILD_LOG]
                     [--build-log-filename BUILD_LOG_FILENAME]
                     [--size-file SIZE_FILE]
                     [--size-json-filename SIZE_JSON_FILENAME]
                     [--config CONFIG [CONFIG ...]]
                     [--config-rules CONFIG_RULES [CONFIG_RULES ...]]
                     [--override-sdkconfig-items OVERRIDE_SDKCONFIG_ITEMS]
                     [--override-sdkconfig-files OVERRIDE_SDKCONFIG_FILES]
                     [--sdkconfig-defaults SDKCONFIG_DEFAULTS]
                     [--check-warnings]
                     [--default-build-targets DEFAULT_BUILD_TARGETS [DEFAULT_BUILD_TARGETS ...]]
                     [--enable-preview-targets] [--include-skipped-apps]
                     [--include-disabled-apps] [--include-all-apps]
                     [--build-verbose] [--parallel-count PARALLEL_COUNT]
                     [--parallel-index PARALLEL_INDEX] [--dry-run]
                     [--keep-going] [--no-preserve]
                     [--ignore-warning-str IGNORE_WARNING_STR [IGNORE_WARNING_STR ...]]
                     [--ignore-warning-strs IGNORE_WARNING_STRS [IGNORE_WARNING_STRS ...]]
                     [--ignore-warning-file IGNORE_WARNING_FILE]
                     [--ignore-warning-files IGNORE_WARNING_FILES [IGNORE_WARNING_FILES ...]]
                     [--copy-sdkconfig]
                     [--collect-size-info COLLECT_SIZE_INFO]
                     [--collect-app-info COLLECT_APP_INFO]
                     [--junitxml JUNITXML]

Named Arguments

--config-file

Path to the config file

--verbose, -v

Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

--log-file

Path to the log file, if not specified logs will be printed to stderr

--no-color

Disable colored output

--manifest-file

[Deprecated] Use –manifest-files instead

--manifest-files

Path to the manifest files which contains the build test rules of the apps

--manifest-filepatterns

space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

--manifest-rootpath

Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

--modified-components

semicolon-separated list of modified components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--modified-files

semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--ignore-app-dependencies-components

[Deprecated] Use –deactivate-dependency-driven-build-by-components instead

--deactivate-dependency-driven-build-by-components, -dc

semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified together with –modified-components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--ignore-app-dependencies-filepatterns

[Deprecated] Use –deactivate-dependency-driven-build-by-filepatterns instead

--deactivate-dependency-driven-build-by-filepatterns, -df

semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified together with –modified-files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

--check-manifest-rules

Check if all folders defined in the manifest files exist. Fail if not

--compare-manifest-sha-filepath

Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

--paths, -p

Paths to the directories containing the apps. By default set to the current directory

--target, -t

Filter the apps by target. By default set to “all”

--build-system

Possible choices: cmake, make

Filter the apps by build system. By default set to “cmake”

--recursive

Search for apps recursively under the specified paths

--exclude

Ignore the specified directories while searching recursively

--work-dir

Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

--build-dir

Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

--build-log

[Deprecated] Use –build-log-filename instead

--build-log-filename

Log filename under the build directory instead of stdout. Can expand placeholders

--size-file

[Deprecated] Use –size-json-filename instead

--size-json-filename

idf.py size output file under the build directory when specified. Can expand placeholders

--config

[Deprecated] Use –config-rules instead

--config-rules

Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

--override-sdkconfig-items

A comma-separated list of key=value pairs to override the sdkconfig items

--override-sdkconfig-files

A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

--sdkconfig-defaults

A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

--check-warnings

Check for warnings in the build output. Fail if any warnings are found

--default-build-targets

space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

--enable-preview-targets

When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

--include-skipped-apps

Include the skipped apps in the output, together with the enabled ones

--include-disabled-apps

Include the disabled apps in the output, together with the enabled ones

--include-all-apps

Include skipped, and disabled apps in the output, together with the enabled ones

--build-verbose

Enable verbose output of the build system

--parallel-count

Number of parallel build jobs in total. Specified together with –parallel-index. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

--parallel-index

Index (1-based) of the parallel build job. Specified together with –parallel-count. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

--dry-run

Skip the actual build, only print the build process

--keep-going

Continue building the next app when the current build fails

--no-preserve

Do not preserve the build directory after a successful build

--ignore-warning-str

[Deprecated] Use –ignore-warning-strs instead

--ignore-warning-strs

space-separated list of patterns. Ignore the warnings in the build output that match the patterns

--ignore-warning-file

[Deprecated] Use –ignore-warning-files instead

--ignore-warning-files

Path to the files containing the patterns to ignore the warnings in the build output

--copy-sdkconfig

Copy the sdkconfig file to the build directory

--collect-size-info

Record size json filepath of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

--collect-app-info

Record serialized app model of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

--junitxml

Path to the junitxml file to record the build results. Can expand placeholder @p

completions

Without –activate option print instructions for manual activation. With the –activate option, add the autocompletion activation script to the shell rc file for bash, zsh, or fish. Other shells are not supported.The –shell option is used only with the –activate option, if provided, add the autocompletion activation script to the given shell; without this argument, will detect shell type automatically. May need to restart or re-login for the autocompletion to start working

idf-build-apps completions [-h] [-a] [-s {bash,zsh,fish}]

Named Arguments

-a, --activate

Activate autocompletion automatically and permanently.

Default: False

-s, --shell

Possible choices: bash, zsh, fish

Specify the shell type for the autocomplete activation script.

dump-manifest-sha

Dump the manifest files SHA values. This could be useful in CI to check if the manifest files are changed.

idf-build-apps dump-manifest-sha [-h] [--config-file CONFIG_FILE] [--verbose]
                                 [--log-file LOG_FILE] [--no-color]
                                 --manifest-files MANIFEST_FILES
                                 [MANIFEST_FILES ...] --output OUTPUT

Named Arguments

--config-file: Path to the config file
--verbose, -v: Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG
--log-file: Path to the log file, if not specified logs will be printed to stderr
--no-color: Disable colored output
--manifest-files: Path to the manifest files which contains the build test rules of the apps
--output, -o: Path to the output file to record the sha256 hash of the manifest rules