CLI Commands
This page is the entry point for the CLI command reference. For a task-oriented overview of the CLI and usage patterns, see CLI Overview.
idf-ci
ESP-IDF CI CLI Tool.
Usage
idf-ci [OPTIONS] COMMAND [ARGS]...
Options
- -c, --config-file <config_file>
Path to the idf-ci config file
- --config <config>
Override settings via dot-path assignments (repeatable). Format: path.to.key = value. Values use Python literal syntax (ast.literal_eval): 10, True, “str”, {..}, [..]. Precedence: CLI > init > config file > defaults
- --debug
Enable debug logging
build
Group of build related commands
Usage
idf-ci build [OPTIONS] COMMAND [ARGS]...
collect
Collect all applications, corresponding test cases and output the result in JSON format.
Usage
idf-ci build collect [OPTIONS]
Options
- -p, --paths <paths>
List of directories to process. Support passing multiple times.
Example:–paths component_1 –paths component_2-p component_1 -p component_2
- -o, --output <output>
Output destination. Stdout if not provided
- --format <output_format>
Output format
- Options:
json | html
- --include-only-enabled-apps
Include only enabled apps
init
Create .idf_build_apps.toml with default values
Usage
idf-ci build init [OPTIONS]
Options
- --path <path>
Path to create the config file
run
Execute the build process for applications
Usage
idf-ci build run [OPTIONS]
Options
- -p, --paths <paths>
List of directories to process. Support passing multiple times.
Example:–paths component_1 –paths component_2-p component_1 -p component_2
- -t, --target <target>
Target to be processed. Or “all” to process all targets.
- --parallel-index <parallel_index>
Index of the parallel build
- --parallel-count <parallel_count>
Number of parallel builds
- -k, --filter-expr <filter_expr>
Pytest filter expression, “-k” option
- -m, --marker-expr <marker_expr>
Pytest marker expression, “-m” option
- --modified-files <modified_files>
Semicolon separated list of files that have been modified
Run build only for test-related apps
Run build only for non-test-related apps
- --dry-run
Run build in dry-run mode
- --build-system <build_system>
Filter the apps by build system. Can be “cmake”, “make” or a custom App class path in format “module:class”
completions
Instructions to enable shell completions for idf-ci.
Usage
idf-ci completions [OPTIONS]
config
Inspect and manage idf-ci configuration.
Usage
idf-ci config [OPTIONS] COMMAND [ARGS]...
explain
Explain a config key, including type, default, and description.
Usage
idf-ci config explain [OPTIONS] CONFIG_KEY
Arguments
- CONFIG_KEY
Required argument
show
Show the effective configuration after all overrides are applied.
Usage
idf-ci config show [OPTIONS] CONFIG_KEY
Arguments
- CONFIG_KEY
Required argument
gitlab
Group of gitlab related commands
Usage
idf-ci gitlab [OPTIONS] COMMAND [ARGS]...
build-child-pipeline
Generate build child pipeline yaml file.
Usage
idf-ci gitlab build-child-pipeline [OPTIONS] [YAML_OUTPUT]
Options
- -p, --paths <paths>
List of directories to process. Support passing multiple times.
Example:–paths component_1 –paths component_2-p component_1 -p component_2
- --modified-files <modified_files>
Semicolon separated list of files that have been modified
- --compare-manifest-sha-filepath <compare_manifest_sha_filepath>
Path to the recorded manifest sha file generated by idf-build-apps dump-manifest-sha
Arguments
- YAML_OUTPUT
Optional argument
download-artifacts
Download artifacts from S3 storage or via presigned URLs.
This command downloads artifacts from S3 storage when credentials are available, or from presigned URLs when S3 credentials are not available. The artifacts are downloaded to the specified folder (or current directory if not specified).
When using –pipeline-id, the command will download the presigned.json file from the specified pipeline and use it to download artifacts. This option cannot be used together with –presigned-json.
Usage
idf-ci gitlab download-artifacts [OPTIONS] [FOLDER]
Options
- --type <artifact_type>
Type of S3 artifacts to upload/download. If not specified, processes all types.
- --commit-sha <commit_sha>
Commit SHA to download artifacts from. If not provided, will try to get it from: 1) PIPELINE_COMMIT_SHA env var, 2) latest commit from branch.
- --branch <branch>
Git branch to use. If not provided, will use current git branch.
- --presigned-json <presigned_json>
Path to the presigned.json file.
- --pipeline-id <pipeline_id>
GitLab pipeline ID to download presigned.json from. Cannot be used together with –presigned-json.
Arguments
- FOLDER
Optional argument
download-known-failure-cases-file
Download known failure cases file from S3 storage.
Usage
idf-ci gitlab download-known-failure-cases-file [OPTIONS] FILENAME
Arguments
- FILENAME
Required argument
generate-presigned-json
Generate presigned URLs for artifacts in S3 storage.
This command generates presigned URLs for artifacts that would be uploaded to S3 storage. The URLs can be used to download the artifacts directly from S3.
Usage
idf-ci gitlab generate-presigned-json [OPTIONS] [FOLDER]
Options
- --commit-sha <commit_sha>
Commit SHA to download artifacts from. If not provided, will try to get it from: 1) PIPELINE_COMMIT_SHA env var, 2) latest commit from branch.
- --branch <branch>
Git branch to use. If not provided, will use current git branch.
- --type <artifact_type>
Type of S3 artifacts to upload/download. If not specified, processes all types.
- --expire-in-days <expire_in_days>
Expiration time in days for the presigned URLs (default: 4 days)
- -o, --output <output>
Path to save the generated presigned URLs. If not specified, will print to stdout.
Arguments
- FOLDER
Optional argument
pipeline-variables
Output dynamic pipeline variables.
Analyzes the current GitLab pipeline environment and determines what variables to set for controlling pipeline behavior. Outputs variables in the format KEY=”VALUE” for each determined variable, which can be used with GitLab’s export feature.
As for the generated variables, please refer to the following link:
Usage
idf-ci gitlab pipeline-variables [OPTIONS]
test-child-pipeline
Generate test child pipeline yaml file.
Usage
idf-ci gitlab test-child-pipeline [OPTIONS] [YAML_OUTPUT]
Arguments
- YAML_OUTPUT
Optional argument
upload-artifacts
Upload artifacts to S3 storage.
This command uploads artifacts to S3 storage only. GitLab’s built-in storage is not supported. The commit SHA is required to identify where to store the artifacts.
Usage
idf-ci gitlab upload-artifacts [OPTIONS] [FOLDER]
Options
- --type <artifact_type>
Type of S3 artifacts to upload/download. If not specified, processes all types.
- --commit-sha <commit_sha>
Commit SHA to download artifacts from. If not provided, will try to get it from: 1) PIPELINE_COMMIT_SHA env var, 2) latest commit from branch.
- --branch <branch>
Git branch to use. If not provided, will use current git branch.
Arguments
- FOLDER
Optional argument
init
Create .idf_ci.toml with default values.
Usage
idf-ci init [OPTIONS]
Options
- --path <path>
Path to create the config file
test
Group of test related commands.
Usage
idf-ci test [OPTIONS] COMMAND [ARGS]...
collect
Collect and process pytest cases.
Usage
idf-ci test collect [OPTIONS] [PATHS]...
Options
- -t, --target <target>
Target to be processed. Or “all” to process all targets.
- -k, --filter-expr <filter_expr>
Pytest filter expression, “-k” option
- -m, --marker-expr <marker_expr>
Pytest marker expression, “-m” option
- --format <_format>
Output format
- Options:
raw | github
- -o, --output <output>
Output destination. Stdout if not provided
Arguments
- PATHS
Optional argument(s)
init
Create pytest.ini with default values.
Usage
idf-ci test init [OPTIONS]
Options
- --path <path>
Path to create the config file