Compote CLI
compote is a command-line tool for the IDF Component Manager. It works with the ESP Component Registry, ESP-IDF projects, and components without requiring an 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 ALL users, you may have to log out and log in again to your shell session for the changes to take effect.
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 the flag "--install" is set. Instead of making real file system changes, logs will be printed if this flag is set.
cache
Group of commands for managing the cache of the IDF Component Manager.
compote cache [OPTIONS] COMMAND [ARGS]...
clear
Clear the component cache.
compote cache clear [OPTIONS]
path
Print the cache path.
compote cache path [OPTIONS]
size
Print the cache size in a human-readable format.
compote cache size [OPTIONS]
Options
- --bytes
Print size in bytes
component
Group of commands for interacting with components.
compote component [OPTIONS] COMMAND [ARGS]...
delete
Delete the specified version of a 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 a 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 the version if it is not defined in the manifest. Use "git" to get the version from the Git tag. (The command will fail if not running from a Git tag.)
- --dest-dir <dest_dir>
Destination directory for the component archive.
- --repository <repository>
The URL of the component repository. This option overrides the value in the idf_component.yml file.
- --commit-sha <commit_sha>
Git commit SHA of the component version. This option overrides the value in the idf_component.yml file.
- --repository-path <repository_path>
Path to the component in the repository. This option overrides the value in the idf_component.yml file.
upload
Upload a component to the component registry.
If the component does not 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 the version if it is not defined in the manifest. Use "git" to get the version from the Git tag. (The command will fail if not running from a Git tag.)
- --dest-dir <dest_dir>
Destination directory for the component archive.
- --repository <repository>
The URL of the component repository. This option overrides the value in the idf_component.yml file.
- --commit-sha <commit_sha>
Git commit SHA of the component version. This option overrides the value in the idf_component.yml file.
- --repository-path <repository_path>
Path to the component in the repository. This option overrides the value in the idf_component.yml file.
- --archive <archive>
Path to the archive of the 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 the given component version is already uploaded and exit.
- --allow-existing
Return success if existing version is already uploaded.
- --dry-run
Upload the 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 status of a component upload.
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 the specified version of a component from the component registry. A 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.
- --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
config
Group of commands to edit the global configuration of the IDF Component Manager by editing "idf_component_manager.yml". By default, the configuration file is located in the ".espressif" directory in your home directory, but the path can be configured with the environment variable "IDF_TOOLS_PATH".
compote config [OPTIONS] COMMAND [ARGS]...
list
List all profiles with tokens hidden.
- If the config file looks like this:
- profiles:
- default:
default_namespace: namespace
empty_profile: another_profile:
default_namespace: another_namespace
- some_other_profile:
aaa: bbb
The 'empty_profile' and 'some_other_profile' will not be printed.
compote config list [OPTIONS]
path
Show path to config file.
compote config path [OPTIONS]
set
Set one or more configuration values in a profile. Creates the profile if it doesn't exist.
compote config set [OPTIONS]
Options
- --profile <profile>
The name of the profile to change or add. If not provided, the default profile will be used.
- --registry-url <registry_url>
Set URL of the Component Registry.
- --storage-url <storage_url>
Set one or more storage URLs. To set a list of values, use this argument multiple times: --storage-url <url1> --storage-url <url2>
- --local-storage-url <local_storage_url>
Set one or more local storage URLs. To set a list of values, use this argument multiple times: --local-storage-url <url1> --local-storage-url <url2>
- --api-token <api_token>
Set API token.
- --default-namespace <default_namespace>
Set default namespace for components.
unset
Unset specific configuration fields or remove the entire profile from the config file. Use --all to delete the entire profile, be careful if you have unsupported/your own fields under profile.
compote config unset [OPTIONS]
Options
- --profile <profile>
The name of the profile to change. If not provided, the default profile will be used.
- --registry-url
Remove URL of the Component Registry.
- --storage-url
Remove storage URLs.
- --local-storage-url
Remove local storage URLs.
- --api-token
Remove API token.
- --default-namespace
Remove default namespace
- --all
Remove the profile entirely from the config file.
manifest
Group of commands for managing the project manifest.
compote manifest [OPTIONS] COMMAND [ARGS]...
add-dependency
Add a dependency to the manifest file.
By default:
If you run the command in a project directory, the dependency will be added to the manifest in the "main" directory.
If you run the command in a component directory, the dependency will be added to the manifest in that directory.
You can explicitly specify a directory using the --path option.
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 if 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, or 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 a manifest file for the specified component.
By default:
If you run the command in a project directory, the manifest will be created in the "main" directory.
If you run the command in a component directory, the manifest will be created in that directory.
You can explicitly specify a 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 if the path is specified.
schema
Print the 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 following format: 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
The 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 to 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 the 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 the browser; only print the login URL to the terminal.
- --description <description>
Description of the token for future reference.
- --default-namespace <default_namespace>
Default namespace to use for components.
- --registry-url <registry_url>
URL of the registry to use.
Environment variables
- IDF_COMPONENT_PROFILE
Provide a default for
--profile
logout
Log out 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 a 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>
Set the frequency (in seconds) for component synchronization. If set to 0, the program will run once and then terminate.
- -R, --recursive
Search for 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 each component will be synced.
- Options:
all | latest
Arguments
- PATH
Required argument
Environment variables
- IDF_COMPONENT_PROFILE
Provide a default for
--profile
version
Print the version of the IDF Component Manager.
compote version [OPTIONS]