Manual installation¶

Run the commands of the typical installation in PowerShell, bash, or zsh. First read Target, prerequisites, and project folder for target selection, prerequisites, and the project/workspace folder requirements.

Typical installation

Install all compatible contexts with setup.

Typical installation

Custom installation

Choose contexts and services interactively.

Custom installation

STM32CubeCLI installation¶

Skip this step if cube --version prints a version.

irm https://developer.st.com/bundles/install/install.ps1 | iex

For Linux, macOS, and Windows with Git Bash, WSL, or MSYS2:

curl -fsSL https://developer.st.com/bundles/install/install.sh | bash -

The script installs STM32CubeCLI for the current user in ~/.local/stm32cube and adds ~/.local/stm32cube/bin to PATH. It does not require administrator rights. Open a new terminal, then check the installation:

cube --version

STM32CubeCLI is distributed under the SLA0048 software license agreement. See Licenses.

Typical installation¶

Install the installer, then use setup to install and deploy all contexts compatible with your selected editor and AI coding agent. GitHub Copilot in VS Code is the default target. Add the target options shown in Setup commands to choose another supported editor or CLI agent. Run the commands from a working directory and choose a project folder beneath it. The commands use the latest installer available to STM32CubeCLI. They do not pin an installer or context version.

Run installer installation and updates outside a deployed project’s bundle lock so the project does not select an older installer version.

cube bundle install --yes cube-agentic-ai-installer
cube bundle update cube-agentic-ai-installer

# Optional: preview setup without making changes
cube agentic-ai setup --project-folder .\my-agentic-ai-project --python venv --dry-run
# Default VS Code target: install declared extension dependencies
cube agentic-ai setup --project-folder .\my-agentic-ai-project --python venv --install-vscode-extensions

cube bundle install --yes cube-agentic-ai-installer
cube bundle update cube-agentic-ai-installer

# Optional: preview setup without making changes
cube agentic-ai setup --project-folder ./my-agentic-ai-project --python venv --dry-run
# Default VS Code target: install declared extension dependencies
cube agentic-ai setup --project-folder ./my-agentic-ai-project --python venv --install-vscode-extensions

For other editor and CLI targets, use the matching options in Setup commands.

The commands perform two stages:

Installer installation. cube bundle install installs the installer, which provides the cube agentic-ai command. Accept the license agreement when prompted. cube bundle update updates an existing installer.

Project setup. setup installs compatible STM32Cube Agentic Contexts and their tool dependencies on the machine. It creates my-agentic-ai-project under the working directory, deploys the contexts and their services into it, and checks the result. It asks no questions. Running it accepts the license agreements listed in data.licenses. Installation progress is printed and can take several minutes. If interrupted before deployment, run setup again to resume. After deployment, run doctor <project folder> --fix instead.

setup prints one JSON result. Check ok, data.status, data.readiness, and data.nextSteps.

Important

ALL_DEPLOYED confirms deployment, not dependency readiness. Setup can return ALL_DEPLOYED with ACTION_REQUIRED or CHECK_MANUALLY, for example when a declared requirement needs attention. Follow data.nextSteps and run cube agentic-ai doctor <project-folder> --fix for resolvable requirements. Complete remaining manual prerequisites, then rerun doctor to check readiness. Do not rerun setup on the deployed project. For VS Code extension setup or repair, see VS Code extension setup and repair.

Setup commands¶

After installing or updating the installer above, choose one target below and run only its command instead of the typical setup command. Each example uses a separate project folder. The same syntax works in PowerShell, bash, or zsh.

cube agentic-ai setup --project-folder ./vscode_copilot_project/ --install-vscode-extensions --python venv

cube agentic-ai setup --project-folder ./copilot_cli_project/ --python venv --ide none

cube agentic-ai setup --project-folder ./vscode_claude_code_project/ --python venv --ide vscode --agentic-system claude-code --install-vscode-extensions

cube agentic-ai setup --project-folder ./claude_code_cli_project/ --python venv --ide none --agentic-system claude-code

cube agentic-ai setup --project-folder ./cursor_ide_project/ --python venv --ide cursor --agentic-system cursor

cube agentic-ai setup --project-folder ./cursor_cli_project/ --python venv --ide none --agentic-system cursor

For deployment layouts and target-specific behavior, see Target, prerequisites, and project folder.

VS Code extension setup and repair¶

This section applies only to VS Code targets. GitHub Copilot in VS Code requires the GitHub Copilot Chat extension (GitHub.copilot-chat), and Claude Code in VS Code requires Anthropic’s Claude Code extension. The installer does not install or manage these host extensions. Install the appropriate host extension before using its agent. See the GitHub Copilot Chat extension Marketplace page and the Claude Code for VS Code guide.

The typical setup command uses the Default VS Code profile and includes --install-vscode-extensions so setup runs code to install declared context extensions. Remove the flag to install them manually. To use an existing named profile, add --vscode-profile "<exact profile name>". The toolkit does not install or manage the host extensions required by Copilot Chat or Claude Code.

For an already deployed project, doctor --fix installs declared extensions only when you pass an explicit --vscode-profile. Without that option, doctor --fix still resolves other declared requirements and reports extension commands for manual installation in the Default profile. For the Default profile, if the result includes data.vscodeProfile, run its verifyCommand and then its installCommands. Reload VS Code after installing the extensions. To authorize extension repair in an existing named profile, run:

cube agentic-ai doctor <project-folder> --fix --vscode-profile "<exact existing profile name>"

Finish installation¶

Use this checkpoint after either typical or custom installation, including installation by an AI agent. Replace <project-folder> with the folder you deployed.

Check the command result: ok must be true. For deployment, data.status: ALL_DEPLOYED confirms that files were deployed, not that all dependencies are ready. Follow data.readiness and data.nextSteps. Use cube agentic-ai doctor <project-folder> --fix for resolvable requirements. For target-specific extension installation, profile, and repair instructions, follow Target, prerequisites, and project folder.
Complete reported manual prerequisites and apply any returned data.hostInstructionUpdate.
Open the deployed folder with the selected editor or start the selected CLI agent from that folder. Use data.openCommand when present. Follow the selected host’s instructions for opening or reloading the project. Keep the project as the top-level workspace folder.
Approve the project MCP servers in the selected agent. The installer cannot grant this permission. Follow the agent-specific MCP approval steps.
Ask the agent to list the services deployed in this project, then make one read-only request using a deployed context:
```
List the STM32 services deployed in this project.
```

To assess dependency status and readiness without changing the project, run cube agentic-ai doctor <project-folder> without --fix. This check is read-only. A host integration check can remain CHECK_MANUALLY. Verify it in the selected editor or agent.

The first-use check is complete when the selected service returns a sourced result and you have resolved or explicitly verified the reported manual checks. Service discovery alone does not prove that an MCP server can start. For startup failures, inspect the agent’s server status and logs. doctor does not diagnose arbitrary MCP or agent-host failures.

Next, follow Try it out for a development task. For Build and DAP Debug, also follow the context’s project-discovery and configuration requirements before building or debugging.

Customization¶

setup options choose the target, the folder and the contexts. Add them to the setup command:

Option	Effect
`--project-folder "<path>"`	Project top folder, created when missing. Use the top-level folder of an existing folder only if it has not already been deployed by the installer. A folder with `.cube-ai/services-lock.json` is refused.
`--contexts <bundle,...>`	Install only these contexts, for example `cube-agentic-ai-esw,cube-agentic-ai-mx2-skill`.
`--python venv` or `--python "<path>"`	Where the Python packages of the contexts go: a dedicated environment, or an existing Python.
`--vscode-profile "<name>"`	VS Code profile for the extensions. Repeat the option for several profiles.
`--install-vscode-extensions`	Let `setup` run `code` to install the declared extensions. VS Code target only.
`--upgrade-installed-in-range`	Upgrade eligible machine bundles before deploying into a folder not yet deployed by this installer.
`--dry-run`	Report what `setup` would do, and change nothing.

For supported targets, options, project file layouts, and VS Code-only context availability, see Target, prerequisites, and project folder.

Custom installation¶

setup does the two steps below in one command. Run them separately to choose the contexts and the services one by one:

cube bundle install --yes cube-agentic-ai-installer
cube bundle update cube-agentic-ai-installer
cube agentic-ai machine-bootstrap --upgrade-installed-in-range
New-Item -ItemType Directory -Path .\my-agentic-ai-project
Set-Location .\my-agentic-ai-project
cube agentic-ai project-deploy-installed . --mode interactive --services-mode interactive
cube agentic-ai doctor . --fix

cube bundle install --yes cube-agentic-ai-installer
cube bundle update cube-agentic-ai-installer
cube agentic-ai machine-bootstrap --upgrade-installed-in-range
mkdir -p ./my-agentic-ai-project
cd ./my-agentic-ai-project
cube agentic-ai project-deploy-installed . --mode interactive --services-mode interactive
cube agentic-ai doctor . --fix

These commands use the default VS Code target. If doctor returns data.vscodeProfile, run its verification and extension-install commands as described in VS Code extension setup and repair. For another supported target, add the options from Target, prerequisites, and project folder to project-deploy-installed. For custom deployment, doctor uses the saved Python choice or automatic detection. It has no --python option. To select a Python runtime explicitly, choose the typical route with setup --python before deployment. See the eSW Python troubleshooting for detection and environment details.

Continue with Finish installation.

Existing project¶

setup --project-folder "<path>" can deploy into a folder that already exists, provided it has not already been deployed by the installer (there is no .cube-ai/services-lock.json). Setup refuses a deployed project with SETUP_PROJECT_ALREADY_DEPLOYED. For an existing deployed project, use project-add or project-remove and then doctor --fix. See Updates. Build and DAP Debug workflows require the project folder to be the top-level folder opened as the VS Code workspace.

Updates¶

To install newer eligible context versions on the machine, first update the installer if needed, then run machine-bootstrap. This does not change the versions already deployed in a project:

cube bundle update cube-agentic-ai-installer
cube agentic-ai machine-bootstrap --upgrade-installed-in-range true

To update a deployed project, first make the desired context versions available on the machine. Then see which deployed contexts are behind with:

cube agentic-ai doctor <project folder>

For each context that is behind, read data.nextSteps: doctor prints the project-remove, project-add and doctor --fix commands for that project, including its recorded target and the deployed services. If the desired version is not installed yet, run machine-bootstrap --upgrade-installed-in-range true first, then run doctor again. Removing before adding avoids leaving services from the old version in the project.

For a project folder not yet deployed by this installer, setup --upgrade-installed-in-range can upgrade eligible machine bundles before deploying into that folder. It cannot update an already-deployed project.

For extension installation or repair in a named VS Code profile, see VS Code extension setup and repair.

The project housekeeping page of the installer user manual describes this procedure.

Commands and options¶

To assess dependency status and readiness without changing the project, run cube agentic-ai doctor <project folder> without --fix. To resolve the dependencies that the installer can manage, add --fix. To list the contexts deployed in a project, run cube agentic-ai project-lock-show <project folder>. To add one context later, run cube agentic-ai project-add <bundle_name> <project folder> --services all, then doctor <project folder> --bundles <bundle_name> --fix. Only setup and doctor install what a context needs. The commands project-add, project-deploy and project-deploy-installed do not.

To read the concise installer guide, run:

cube agentic-ai get-user-manual --format tldr

The installer user manual describes all commands and options.

Troubleshooting¶

cube: command not found

Open a new terminal. If the command is still not found, add ~/.local/stm32cube/bin to PATH. On Windows, sign out and sign in again to refresh the environment.

code: command not found

The VS Code extensions are not necessarily missing: the terminal could not check them. On macOS, run Shell Command: Install 'code' command in PATH from the VS Code Command Palette. On Windows and Linux, reinstall VS Code or add its bin folder to the PATH. Or install the extensions from the Extensions view of VS Code. See the VS Code command line reference.

Installer not updated

Update the installed installer with cube bundle update cube-agentic-ai-installer, then use cube agentic-ai show-catalog to confirm the contexts available to that installer.

“status”: “PARTIAL”

At least one bundle failed: data.nextSteps names it. Fix the cause, then add it with project-add and run doctor <project folder> --fix: setup refuses a project folder where it has already deployed contexts. For more detail, add diagnostic output:

cube agentic-ai --verbose standard setup

“readiness”: “ACTION_REQUIRED”

A context needs something that setup could not do. Read data.nextSteps of the result, or run cube agentic-ai doctor <project folder>.

Download failure

Check the network connection and the proxy settings, then run the failed command again. Bundles that are already installed are not downloaded again.