Command reference ¶

The cube command runs STM32CubeCLI tools and manages the bundles that provide them. Its command surface changes when bundles are installed, removed, or selected by a project.

Syntax ¶

           cube [GLOBAL_OPTION]... [COMMAND] [ARGUMENT]...
cube bundle [BUNDLE_OPTION]... <OPERATION> [OPERATION_OPTION]... [ARGUMENT]...

Run cube --help to see the commands available in the current environment. Run cube <command> --help or cube bundle <operation> --help for command-specific options.

Global options ¶

--help

Show help, including the commands provided by loaded bundles.

Example: cube --help

--help-license

Show the license agreement for cube.

Example: cube --help-license

--version

Show the cube version.

Example: cube --version

--cwd <directory>

Run as if started in directory. This also controls project discovery.

               cube --cwd ~/projects/blinky bundle show --project

              

cube --cwd C:\Projects\blinky bundle show --project

--json

Use JSON output where the selected operation supports it.

Example: cube --json bundle list

The inspection operations list, show, license, list-deps, list-usages, list-online, list-all-online, and external list support JSON output. Place --json before bundle.

--verbose

Show additional wrapper diagnostics.

Example: cube --verbose bundle list

--list

List loaded bundles.

Example: cube --list

--resolve <command> [arguments]

Show the executable, providing bundle, and exported environment without running the command. Combine with --json for machine-readable output.

Examples: cube --resolve cmake --version and cube --json --resolve cmake --version

--with <version-range>

Select a bundle version matching the range for the following command or runtime.

Example: cube --with ^3.30.0 cmake --version

--detach

Start the selected command as a detached process.

Example: cube --detach http-server

--no-detach

Keep the selected command attached, even if its bundle requests detachment.

Example: cube --no-detach http-server

--show-settings

Show all cube configuration values.

Example: cube --show-settings

--get-current-value <key>

Show the effective value of a configuration key.

Example: cube --get-current-value cmsis_pack_root

--set <key> <value>

Save a value in CubeUserConfig.json under the platform’s user configuration directory. The default location is $XDG_CONFIG_HOME/stm32cube/CubeUserConfig.json on Linux when XDG_CONFIG_HOME is set, or ~/.config/stm32cube/CubeUserConfig.json otherwise; %APPDATA%\stm32cube\CubeUserConfig.json on Windows; and ~/Library/Application Support/stm32cube/CubeUserConfig.json on macOS. Run cube --verbose --show-settings to see the file used by the current environment.

The wrapper recognizes these keys:

cmsis_pack_root: CMSIS Pack storage directory. Example: cube --set cmsis_pack_root /path/to/packs
cube_bundle_path: Installed bundle repository directory. Example: cube --set cube_bundle_path /path/to/bundles
cube_bundle_path_extra: Additional directory searched recursively for bundles. Example: cube --set cube_bundle_path_extra /path/to/extra-bundles
cube_bundle_registry: Online bundle registry URL. Example: cube --set cube_bundle_registry https://example.com/bundles
cube_cache_path: Cache directory. Example: cube --set cube_cache_path /path/to/cache
cube_log_path: Log directory. Example: cube --set cube_log_path /path/to/logs
cube_network_max_redirect: Maximum number of network redirects. Example: cube --set cube_network_max_redirect 10
cube_network_retry: Number of network retry attempts. Example: cube --set cube_network_retry 5
cube_network_timeout: Network timeout in milliseconds. Example: cube --set cube_network_timeout 7200000

--unset <key>

Remove a configuration value.

Example: cube --unset cube_network_retry

Dynamic commands and runtimes ¶

Bundles declare commands and runtimes in CubeBundle.json. cube loads installed bundles and bundles under CUBE_BUNDLE_PATH_EXTRA each time it starts. Bundle commands appear under COMMANDS in cube --help and run as cube <command> [arguments].

Runtimes are executables used internally by bundle commands. They do not appear as commands in cube --help and cannot be invoked directly. When a command uses a runtime, cube resolves the runtime from that command’s bundle dependencies.

The available commands and selected versions depend on:

installed bundle versions;
bundles under CUBE_BUNDLE_PATH_EXTRA;
versions selected by the current project’s lock data;
--with <version-range>, when specified.

Use these commands to inspect the active command surface and its resolution:

           cube --help
cube --list
cube --resolve cmake
cube --json --resolve cmake

          

For example, cube cmake --version runs the cmake command from the selected bundle. If that command uses a runtime, cube resolves and runs the runtime automatically.

Installing or removing a bundle updates the available commands on the next cube invocation. If several installed versions provide the same command, project lock data and --with take precedence. Otherwise, cube selects the latest matching version.

Bundle management ¶

A bundle identifier can be a name, an exact version such as cmake@4.4.0+st.1, or a version range such as cmake@^3.30.0. Use cube bundle <operation> --help for the complete syntax accepted by the installed version.

Examples: cube bundle show cmake, cube bundle show cmake@4.4.0+st.1, and cube bundle show cmake@^3.30.0

Inspect bundles ¶

list

List installed bundles. With --project, list the current project’s direct requirements and resolved bundles instead of every bundle installed in the local repository.

Examples: cube bundle list and cube bundle list --project

show <bundle>...

Show details for installed bundles. With --project, show the current project’s direct requirements and exact resolved bundles instead of accepting bundle identifiers.

Examples: cube bundle show cmake and cube bundle show --project

license <bundle>...

Show bundle license information. With --project, show license information for the bundles resolved by the current project instead of accepting bundle identifiers. With --online, show license information from the registry instead of installed bundles.

Examples: cube bundle license cmake, cube bundle license --project, and cube bundle license --online cmake

list-deps <bundle>...

List the dependencies selected for bundle identifiers.

Example: cube bundle list-deps cmake@^3.30.0

list-usages <bundle>...

List installed bundles that use the specified bundles.

Example: cube bundle list-usages cmake

list-online

List bundles available for this host from the configured registry.

Example: cube bundle list-online

list-all-online

List all bundles in the configured registry, including bundles for other platforms or OSs.

Example: cube bundle list-all-online

Use --tags <tag,...> with online listing operations to filter by bundle tags.

Example: cube bundle --tags build list-online

Install and maintain bundles ¶

The install, download, update, remove, and autoremove commands may ask for confirmation. Place --yes before the operation to accept automatically. Place --no after the operation to decline automatically and inspect the proposed action without applying it.

Examples: cube bundle --yes install cmake and cube bundle install --no cmake

Install or download ¶

install <bundle-or-path>...

Download and install bundles from identifiers or install local .bundle files. Required dependencies are installed automatically.

Example: cube bundle install cmake@^3.30.0

With --project and bundle identifiers, add those bundles as direct project requirements, resolve and update the lock data, and install anything missing. With --project and no identifiers, install missing bundles from the existing project requirements and compatible lock data without adding requirements. --strict stops the installation if it requires a bundle that was not explicitly requested. These two options cannot be combined.

Examples: cube bundle install --project, cube bundle install --project cmake, and cube bundle install --strict cmake

download <bundle>...

Download bundle archives and all their dependencies to the current directory. Installed bundles are downloaded again.

Example: cube bundle download cmake

--platform selects an operating system or a complete architecture and operating-system target. Without it, the current platform is used. With --project, also download the current project’s locked bundles, or resolve its requirements if no lock data exists. Any supplied bundle identifiers are included in the download but are not added to the project.

Examples: cube bundle download --platform x86_64-windows cmake and cube bundle download --project

Update or repair ¶

update [bundle]...

Update the named bundles when newer matching versions are available. Without identifiers, check every locally installed bundle.

Examples: cube bundle update cmake and cube bundle update

fix

Install dependencies missing from any installed bundle.

Example: cube bundle fix

Remove ¶

remove <bundle>...

Remove installed bundles matching each identifier.

Example: cube bundle remove cmake@4.4.0+st.1

If an identifier matches several versions, specify a narrower version or place --all before remove to remove every match. With --project, remove the named direct requirements from the current project and re-resolve its lock data without deleting installed bundle files.

Examples: cube bundle --all remove cmake and cube bundle remove --project cmake

autoremove [bundle]...

Remove unused versions of the named bundles. Without identifiers, check every installed bundle. The latest installed version and versions required by other bundles are always kept.

Examples: cube bundle autoremove cmake and cube bundle autoremove

Projects and reproducibility ¶

See Working with a project for how project lock data makes the toolchain reproducible, and how to register external bundle locations.

Place --force before an operation to continue installation when dependencies are unavailable, or to overwrite conflicting installation and removal work data. Place --all before remove to remove every installed version matching an ambiguous identifier.

Examples: cube bundle --force install cmake and cube bundle --all remove cmake

Create bundles ¶

init

Create a CubeBundle.json template in the current directory. With --project, create .settings/bundles.store.json and initialize project lock data instead of creating a bundle template. Bundle identifiers supplied after --project become direct requirements and are installed as part of initialization.

Examples: cube bundle init and cube bundle init --project cmake

validate

Validate CubeBundle.json in the current directory.

Example: cube bundle validate

package

Package the bundle described by CubeBundle.json in the current directory.

Example: cube bundle package

show-bundle-schema

Print the JSON schema for CubeBundle.json.

Example: cube bundle show-bundle-schema

Environment variables ¶

Environment variables apply to the current process and take precedence over values saved with cube --set. Use the cube --set command to save a value in the user configuration instead.

CUBE_BUNDLE_PATH: Override the installed bundle repository location.
CUBE_BUNDLE_PATH_EXTRA: Add a recursively searched directory of bundles without installing them.
CUBE_BUNDLE_REGISTRY: Override the online bundle registry URL.
CMSIS_PACK_ROOT: Override the CMSIS Pack storage directory.
CUBE_CACHE_PATH: Override the cache directory.
CUBE_LOG_PATH: Override the log directory.
CUBE_NETWORK_MAX_REDIRECT: Set the maximum number of network redirects.
CUBE_NETWORK_RETRY: Set the number of network retry attempts.
CUBE_NETWORK_TIMEOUT: Set the network timeout in milliseconds.

Examples:

             export CUBE_BUNDLE_PATH="$HOME/.local/share/stm32cube/bundles"
export CUBE_BUNDLE_PATH_EXTRA="$HOME/cube-bundles"
export CUBE_BUNDLE_REGISTRY="https://example.com/bundles"
export CMSIS_PACK_ROOT="$HOME/.local/share/stm32cube/packs"
export CUBE_CACHE_PATH="$HOME/.cache/stm32cube"
export CUBE_LOG_PATH="$HOME/.config/stm32cube/logs"
export CUBE_NETWORK_MAX_REDIRECT=10
export CUBE_NETWORK_RETRY=5
export CUBE_NETWORK_TIMEOUT=7200000

            

             $env:CUBE_BUNDLE_PATH = "$HOME\AppData\Local\stm32cube\bundles"
$env:CUBE_BUNDLE_PATH_EXTRA = "C:\CubeBundles"
$env:CUBE_BUNDLE_REGISTRY = "https://example.com/bundles"
$env:CMSIS_PACK_ROOT = "$HOME\AppData\Local\stm32cube\packs"
$env:CUBE_CACHE_PATH = "$HOME\AppData\Local\stm32cube\cache"
$env:CUBE_LOG_PATH = "$HOME\AppData\Local\stm32cube\logs"
$env:CUBE_NETWORK_MAX_REDIRECT = "10"
$env:CUBE_NETWORK_RETRY = "5"
$env:CUBE_NETWORK_TIMEOUT = "7200000"

            

             set "CUBE_BUNDLE_PATH=%LOCALAPPDATA%\stm32cube\bundles"
set "CUBE_BUNDLE_PATH_EXTRA=C:\CubeBundles"
set "CUBE_BUNDLE_REGISTRY=https://example.com/bundles"
set "CMSIS_PACK_ROOT=%LOCALAPPDATA%\stm32cube\packs"
set "CUBE_CACHE_PATH=%LOCALAPPDATA%\stm32cube\cache"
set "CUBE_LOG_PATH=%LOCALAPPDATA%\stm32cube\logs"
set "CUBE_NETWORK_MAX_REDIRECT=10"
set "CUBE_NETWORK_RETRY=5"
set "CUBE_NETWORK_TIMEOUT=7200000"

            

Save persistent values with cube --set instead of setting environment variables:

             cube --set cube_bundle_path /path/to/bundles
cube --set cube_bundle_path_extra /path/to/extra-bundles
cube --set cube_bundle_registry https://example.com/bundles
cube --set cmsis_pack_root /path/to/packs
cube --set cube_cache_path /path/to/cache
cube --set cube_log_path /path/to/logs
cube --set cube_network_max_redirect 10
cube --set cube_network_retry 5
cube --set cube_network_timeout 7200000

            

The effective values and defaults are shown by cube --help and cube --show-settings.