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

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

--resolution <resolution>

Resolution strategy for syncing components. By default, all versions are synced. If set to "latest", only the latest version of the components will be synced.

Options:: all | latest

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]