Compote CLI

The compote is a command-line tool for the IDF Component Manager. It works with ESP component registry, ESP-IDF projects and components without requiring ESP-IDF installation.

compote

compote [OPTIONS] COMMAND [ARGS]...

Options

-W, --warnings-as-errors

Treat warnings as errors.

autocomplete

Generate tab-completion scripts for the specified shell.

For BASH users, you may run:
$ compote autocomplete --shell bash > ~/.compote-complete.bash
$ echo ". ~/.compote-complete.bash" >> ~/.bashrc
For ZSH users, you may run:
$ compote autocomplete --shell zsh > ~/.compote-complete.zsh
$ echo ". ~/.compote-complete.zsh" >> ~/.zshrc
Or you may install the completion file into your $fpath.
~/.zfunc is a commonly used $fpath. You may run:
$ compote autocomplete --shell zsh > ~/.zfunc/_compote
For FISH users, completion files are commonly stored in ~/.config/fish/completions. You may run:
$ compote autocomplete --shell fish > ~/.config/fish/completions/compote.fish

For ALL users, you may have to log out and log in again to your shell session for the changes to take effect.

Besides, you may use:
$ compote autocomplete --shell [SHELL] --install
to create the completion file and inject the sourcing script to your rc files automatically.
You may use also use:
$ compote autocomplete --shell [SHELL] --install --dry-run
to simulate running with the --install flag and check what would be done.
compote autocomplete [OPTIONS]

Options

--shell <shell>

Required Shell type

Options:

bash | zsh | fish

--install

Create the completion files and inject the sourcing script into your rc files if this flag is set.

--dry-run

Only useful when flag "--install" is set. Instead of real file system changes, log would be printed if this flag is set.

cache

Group of commands to manage cache of the IDF Component Manager.

compote cache [OPTIONS] COMMAND [ARGS]...

clear

Clear the cache of components and API client cache.

compote cache clear [OPTIONS]

path

Print the cache path.

compote cache path [OPTIONS]

size

Print the cache size in human-readable format.

compote cache size [OPTIONS]

Options

--bytes

Print size in bytes

component

Group of commands to interact with components.

compote component [OPTIONS] COMMAND [ARGS]...

delete

Delete specified version of the component from the component registry. The deleted version cannot be restored or re-uploaded.

compote component delete [OPTIONS]

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--namespace <namespace>

Namespace for the component. Can be set in config file.

--name <name>

Required Component name

--version <version>

Required Component version to delete.

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

IDF_COMPONENT_NAMESPACE

Provide a default for --namespace

pack

Create component archive and store it in the dist directory.

compote component pack [OPTIONS]

Options

--project-dir <manager>
--name <name>

Required Component name

--version <version>

Set version if not defined in the manifest. Use "git" to get version from the git tag. (command would fail if running not from a git tag)

--dest-dir <dest_dir>

Destination directory for the component archive.

--repository <repository>

The URL of the component repository. This option overwrites the value in the idf_component.yml

--commit-sha <commit_sha>

Git commit SHA of the the component version. This option overwrites the value in the idf_component.yml

--repository-path <repository_path>

Path to the component in the repository. This option overwrites the value in the idf_component.yml

upload

Upload component to the component registry.

If the component doesn't exist in the registry it will be created automatically.

compote component upload [OPTIONS]

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--namespace <namespace>

Namespace for the component. Can be set in config file.

--name <name>

Required Component name

--version <version>

Set version if not defined in the manifest. Use "git" to get version from the git tag. (command would fail if running not from a git tag)

--dest-dir <dest_dir>

Destination directory for the component archive.

--repository <repository>

The URL of the component repository. This option overwrites the value in the idf_component.yml

--commit-sha <commit_sha>

Git commit SHA of the the component version. This option overwrites the value in the idf_component.yml

--repository-path <repository_path>

Path to the component in the repository. This option overwrites the value in the idf_component.yml

--archive <archive>

Path of the archive with a component to upload. When not provided the component will be packed automatically.

--skip-pre-release

Do not upload pre-release versions.

--check-only

Check if given component version is already uploaded and exit.

--allow-existing

Return success if existing version is already uploaded.

--dry-run

Upload component for validation without creating a version in the registry.

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

IDF_COMPONENT_NAMESPACE

Provide a default for --namespace

upload-status

Check the component uploading status.

compote component upload-status [OPTIONS]

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--job <job>

Required Upload job ID

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

yank

Yank specified version of the component from the component registry. Yanked version will only be downloaded if the exact version is specified in the component manifest or lock file. A warning message is printed every time a yanked version is downloaded.

compote component yank [OPTIONS]

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--namespace <namespace>

Namespace for the component. Can be set in config file.

--name <name>

Required Component name

--version <version>

Required Component version to yank version.

--message <message>

Required Message explaining why the component version is being removed from the registry.

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

IDF_COMPONENT_NAMESPACE

Provide a default for --namespace

manifest

Group of commands to manage manifest of the project.

compote manifest [OPTIONS] COMMAND [ARGS]...

add-dependency

Add a dependency to the manifest file.

By default:

If you run the command in the directory with project, the dependency will be added to the manifest in the "main" directory.

If you run the command in the directory with a component, the dependency will be added to the manifest right in that directory.

You can explicitly specify directory using the --path option.

Examples:
- $ compote manifest add-dependency example/cmp
Will add a component example/cmp with constraint *
- $ compote manifest add-dependency example/cmp<=3.3.3
Will add a component example/cmp with constraint <=3.3.3
- $ compote manifest add-dependency example/cmp --registry-url https://components-staging.espressif.com
Will add a component example/cmp from the staging registry with constraint *
- $ compote manifest add-dependency cmp --git https://github.com/espressif/example_components.git --git-path cmp
Will add a component cmp from the git repository with path cmp
compote manifest add-dependency [OPTIONS] DEPENDENCY

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--component <component>

Name of the component in the project where the dependency will be added.

-p, --path <path>

Path to the component where the dependency will be added. The component name is ignored when the path is specified.

--git <git>

Git URL of the component.

--git-path <git_path>

Path to the component in the git repository.

--git-ref <git_ref>

Git reference (branch, tag, commit SHA) of the component.

--registry-url <registry_url>

URL of the registry.

Arguments

DEPENDENCY

Required argument

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

create

Create manifest file for the specified component.

By default:

If you run the command in the directory with project, the manifest will be created in the "main" directory.

If you run the command in the directory with a component, the manifest will be created right in that directory.

You can explicitly specify directory using the --path option.

compote manifest create [OPTIONS]

Options

--project-dir <manager>
--component <component>

Name of the component in the project where the dependency will be added.

-p, --path <path>

Path to the component where the dependency will be added. The component name is ignored when the path is specified.

schema

Print json schema of the manifest file idf_component.yml

compote manifest schema [OPTIONS]

project

Group of project related commands

compote project [OPTIONS] COMMAND [ARGS]...

create-from-example

Create a project from an example.

You can specify EXAMPLE in the format like: namespace/name=1.0.0:example

where "=1.0.0" is a version specification.

An example command:

compote project create-from-example example/cmp^3.3.8:cmp_ex

Namespace and version are optional in the EXAMPLE argument.

compote project create-from-example [OPTIONS] EXAMPLE

Options

--project-dir <manager>
--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

-p, --path <path>

Path of the new project. The project will be created directly in the given folder if it is empty.

Arguments

EXAMPLE

Required argument

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

remove-managed-components

Remove the managed_components folder.

compote project remove-managed-components [OPTIONS]

Options

--project-dir <manager>

registry

Group of commands to work with component registry

compote registry [OPTIONS] COMMAND [ARGS]...

login

Login to the component registry

compote registry login [OPTIONS]

Options

--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--no-browser

Do not open browser and only print login URL to the terminal

--description <description>

Description for the token for future reference

--default-namespace <default_namespace>

Default namespace to use for the components

--registry-url <registry_url>

URL of the registry to use

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

logout

Logout from the component registry. Removes the token from the profile and revokes it on the registry.

compote registry logout [OPTIONS]

Options

--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--no-revoke

Do not revoke the token on the server side when logging out

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

sync

Sync components from the registry to local directory

compote registry sync [OPTIONS] PATH

Options

--profile, --service-profile <profile_name>

Specifies the profile to use for this command. Alias "--service-profile" is deprecated and will be removed.

--project-dir <manager>
--interval <interval>

Sets the frequency (in seconds) for component synchronization. If set to 0, the program will run once and terminate.

-R, --recursive

Search components recursively

--component <component>

Specify the components to sync from the registry. Use multiple --component options for multiple components. Format: namespace/name<version_spec>. Example: example/cmp==1.0.0

Arguments

PATH

Required argument

Environment variables

IDF_COMPONENT_PROFILE

Provide a default for --profile

version

Print version of the IDF Component Manager.

compote version [OPTIONS]