Commands Reference¶

All commands share the same output format and exit-code contract.

Output format: JSON on stdout (success and failure), except help/version output and interactive prompts. Exit codes: 0 = success, non-zero = failure. Prerequisite for all commands: cube must be installed and on PATH.

Global options¶

Place global options before the command name, for example:

cube agentic-ai --verbose progress machine-bootstrap --dry-run

Option	Default	Description
`--verbose none\|progress\|standard\|debug`	`none`	Control diagnostics on stderr. `none`: silent; `progress`: per-item progress for multi-item commands; `standard`: progress plus informational and error messages; `debug`: all diagnostics.
`--help`	off	Print human-readable help. Use `<command> --help` for command-specific options.
`--version`	off	Print the installer version.

Output envelope¶

Non-interactive command execution writes exactly one JSON object to stdout. The envelope fields are identical regardless of success or failure. Interactive commands can print prompts before the final JSON result. For JSON-only automation, use non-interactive service selection and deployment modes, and project-remove --confirm-always when confirmation would otherwise be required. Help and version requests print text instead of an envelope.

Success¶

{
  "ok": true,
  "command": "<stable-command-id>",
  "timestamp": "<ISO-8601 UTC>",
  "data": {}
}

Field	Type	Description
`ok`	`true`	Always `true` on success.
`command`	string	Stable command identifier, e.g. `"machine-bootstrap"`.
`timestamp`	string	ISO-8601 UTC timestamp of command execution, e.g. `"2026-08-06T10:00:00.000Z"`.
`data`	object	Command-specific payload. Shape varies per command; each command section below documents its fields and status codes.

Failure¶

{
  "ok": false,
  "command": "<stable-command-id>",
  "timestamp": "<ISO-8601 UTC>",
  "error": {
    "code": "UPPERCASE_ERROR_CODE",
    "message": "Human-readable description of the failure.",
    "cause": "Root-cause detail for diagnostics.",
    "details": {}
  }
}

Field	Type	Description
`ok`	`false`	Always `false` on failure.
`command`	string	Stable command identifier.
`timestamp`	string	ISO-8601 UTC timestamp of command execution.
`error.code`	string	Stable uppercase error code, e.g. `CATALOG_NOT_FOUND`. The full list with recovery guidance is in Troubleshooting → Error codes.
`error.message`	string	Human-readable failure description.
`error.cause`	string	Root-cause detail intended for diagnostics.
`error.details`	object?	Optional structured context (present only when additional machine-readable detail is available).

Parsing guidance¶

Read ok first to branch between success and failure paths.
On success, the command-specific payload is always under data.
On failure, the structured reason is always under error.code and error.message. Do not try to parse error.message programmatically. Use error.code for branching.
ok: true does not always mean every sub-operation succeeded. Multi-item commands can report partial outcomes inside data. Inspect command-specific aggregate status fields and per-item statuses as documented in each command section.
timestamp is informational. Do not use it for flow control.
In non-interactive command execution, no other text is written to stdout. Progress messages and diagnostics go to stderr.

Key concepts¶

See Concepts for the conceptual model (bundle lifecycle, SemVer/version selection, machine vs project scope, lock files, orchestration catalog, and additive deployment behavior).

Commands¶

setup and doctor are the entry commands: they cover the whole journey of installing the toolkit and checking that it works. The other commands are the building blocks they use, for advanced control (pinned versions, selected services, presets, removal, upgrades).

Only setup and doctor handle the requirements that contexts declare: Python packages, tool bundles such as the STM32CubeMX2 application, and VS Code extensions. The building blocks (machine-bootstrap, machine-install, project-add, project-deploy, project-deploy-installed) never check or resolve them. After one of them, run cube agentic-ai doctor <project_top_folder> --fix to install what the deployed contexts need, and read its data.nextSteps for what only you can do.

setup¶

Install the toolkit on the machine and deploy it into a project in one run: install the contexts the target can use, resolve the dependencies they declare, create the project folder, deploy the contexts into it, and diagnose the result. The request is the consent: nothing is asked during the run.

cube agentic-ai setup [options]

Option	Default	Description
`--project-folder <path>`	`<home>/my-agentic-ai-project`	Project top folder, created when missing. The home folder and file system roots are refused (`PROJECT_FOLDER_UNSAFE`).
`--contexts <bundle,...>`	all contexts the target can use	Install only these catalog bundles. The installer bundle, which carries the housekeeping and doctor skills, is always added. A context that needs VS Code fails with another IDE target (`CONTEXT_REQUIRES_VSCODE`).
`--python <value>`	`auto`	Python used for context packages: `auto`, `venv`, or the absolute path of a Python executable. The choice is saved per project and ESW bundle version in `.cube-ai/esw-python/<bundle>@<version>.json`. `venv` uses the ESW bundle-version environment; projects selecting `venv` for that version share it, while each project can independently select a system Python or path.
`--vscode-profile <name>`	the Default profile	VS Code target only. Profile that receives the extensions; repeat the option for several profiles. The exact profile name is used; invalid names are refused.
`--ide <id>`	`vscode`	IDE target. See Target selection.
`--agentic-system <id>`	`github-copilot`	Agentic system target.
`--canonical`	off	Deploy under the `.cube-ai/` canonical layout only.
`--upgrade-installed-in-range [true\|false]`	`false`	`true`: upgrade eligible context bundles on the machine before deploying this new project, as `machine-bootstrap` does. `setup` refuses a project that already has a services lock, so this option does not update deployed project contexts. Use `machine-bootstrap --upgrade-installed-in-range true`, then the replacement commands from `doctor`, for an existing project. The installer bundle follows the installer version and is never upgraded by `setup`.
`--install-vscode-extensions`	off	Opt-in. The installer runs `code` itself to install the extensions that the installed contexts declare, in each `--vscode-profile` or in the Default profile. It applies to the VS Code target only (`--ide vscode`, the default, without `--canonical`): with another IDE it is skipped, and a log line, the warning `VSCODE_INSTALL_SKIPPED`, a next step and `data.vscodeInstall.reason` say why. It is also skipped when no installed context declares an extension or `code` is not on the `PATH`. It lists each profile first and skips one that cannot be listed (it never creates a profile), leaves an installed extension as it is (never `--force`), and reports each extension in `data.vscodeInstall`.
`--dry-run`	off	Report what `setup` would do and change nothing. See the limits below.

Behavior:

A project folder may already contain user files, but if it has a services lock (.cube-ai/services-lock.json) setup refuses it with SETUP_PROJECT_ALREADY_DEPLOYED, before anything is installed. Use setup only for a folder not yet deployed by this installer. To change contexts in a deployed project, use project-add or project-remove, then doctor <project_top_folder> --fix.
A bundle that fails to install does not stop the others. In that case, data.status is PARTIAL. Read data.bundles[], data.deploymentFailures[] and data.nextSteps[]. The next steps give complete project-add and bundle-scoped doctor --fix commands to retry a failed installation or deployment. Setup itself cannot be rerun after any context was deployed. If every bundle installation fails, setup returns ALL_BUNDLES_FAILED before creating the project folder, and can be retried after fixing the cause.
Python choices are project-scoped and made once, when setup creates the project. Setup cannot change the choice of a deployed project. Setup passes the target project folder to declared Python checks and resolutions, and stores the selected interpreter under .cube-ai/esw-python/<bundle>@<version>.json. The Python executable itself is never installed. A new ESW bundle version without a choice file starts from the project’s most recent choice. Another project can choose a different interpreter. See Python of the eSW context.
An ESW setup checks and applies its idempotent Python dependency resolution even when the declared package ranges already pass, so the requested choice is recorded for that project. --dry-run does not write the setting.
Progress goes to stderr: a line per step and per bundle, and a line every 10 seconds while a bundle installs or a resolution runs. A fresh installation can take several minutes: allow a long timeout, or run it in the background. Running it again resumes when it stopped before deploying. Once it has deployed, finish with doctor <project_top_folder> --fix. stdout carries only the JSON result. --verbose none silences stderr.
All services of each context are deployed. To select services or pin versions, use project-add.

Outcome:

Returns: data.status (ALL_DEPLOYED or PARTIAL), data.readiness (READY, CHECK_MANUALLY or ACTION_REQUIRED), data.bundles[], data.deployed[], data.deploymentFailures[], data.resolutions[], data.licenses[], data.requirements[], data.blockedServices[], data.unavailableContexts[], data.notices[], and data.nextSteps[]. ALL_DEPLOYED describes bundle deployment, not requirement readiness. Read data.readiness and data.nextSteps for remaining work.
data.licenses[] reports the identifiers declared by installed bundles. The context bundles declare SLA0044 Rev 7 - February 2026. STM32CubeCLI remains under SLA0048.
VS Code target: when an installed context declares an extension, data.vscodeExtensions[] lists the declared extensions. data.vscodeProfiles[] gives, for each profile, a verifyCommand to list its extensions, one installCommands entry per declared extension (VS Code leaves an installed one unchanged), and an openCommand. data.openCommand opens the project in the first profile of data.vscodeProfiles[] (the Default profile when none is named): run the verifyCommand of that profile first, and do not run the open command if the profile is not found, because VS Code would create an empty profile of that name. data.recommendations reports the update of .vscode/extensions.json: status is ADDED, UNCHANGED or NOT_UPDATED. A file that has comments or an unexpected shape is not rewritten: status is NOT_UPDATED, reason says why, and the extensions to add are the data.vscodeExtensions[] entries. RECOMMENDATIONS_NOT_WRITTEN is raised only when writing the file fails. During setup, code runs only with --install-vscode-extensions; otherwise the agent or user runs the returned commands after verifying the profile.

Who runs code: setup returns extension commands unless --install-vscode-extensions is supplied. Doctor returns commands unless both --fix and an explicit --vscode-profile "<name>" are supplied. That combination verifies the named profile and installs missing declared extension dependencies there. Doctor never installs into an implicit Default profile. The commands follow the VS Code command line reference:

Purpose	Command	Notes
List the extensions of a profile (`verifyCommand`)	`code --list-extensions --profile "<name>"`	Without `--profile`, the Default profile. For a profile that does not exist it reports that it was not found and creates nothing. Compare the extension ids without case.
Install an extension (`installCommands`)	`code --install-extension <publisher.extension> --profile "<name>"`	An extension that is already installed is left as it is. `--force` is never used, because it would update an extension that the user already has.
Open the project (`openCommand`)	`code "<project folder>" --profile "<name>"`	For a profile that does not exist, VS Code creates an empty profile of that name, so run it only after the verification.

Every path and profile name is in double quotes, so the commands can be pasted in PowerShell, cmd, bash and zsh. VS Code Insiders is started with code-insiders, which setup does not look for.

No declared extension: nothing needs code, so data.vscodeProfiles is empty, there is no data.openCommand, and the next step says to open the project folder in VS Code. A --vscode-profile option has no effect then, and a next step says so.
code not on the PATH: data.vscodeCli.onPath is false and the warning VSCODE_CLI_NOT_FOUND is raised. Run none of the VS Code commands: the extensions were not checked, so they are not necessarily missing. Install them from the Extensions view, or accept the proposal that VS Code makes when the folder opens. To get code: on macOS, run the Command Palette command “Shell Command: Install ‘code’ command in PATH” (named “Install ‘code’ and optionally ‘copilot’ commands in PATH” in recent versions); on Windows and Linux, reinstall VS Code or add its bin folder to the PATH (Windows default: AppData\Local\Programs\Microsoft VS Code\bin).
Routing instruction: data.hostInstructionUpdate holds the instruction to add to the host instruction file so that the agent consults the routing skill. data.hostInstructionUpdate.instructionFile names that file for the selected agentic system (.github/copilot-instructions.md for GitHub Copilot, CLAUDE.md for Claude Code, AGENTS.md for Cursor). A next step repeats it.
Other IDE targets: the next step is to start your agent in the project folder.
Exit code: 0 whenever the installation ran, including with unmet prerequisites. Read data.readiness.
Machine level: installs Cube bundles and runs the commands that bundles declare as resolutions.
Project level: creates the project folder, deploys the contexts, writes both project locks, recommends extensions, and stores the ESW Python choice under .cube-ai/esw-python/ when an ESW Python dependency is resolved.

Dry run limits (--dry-run): the requirements of a bundle are declared in the bundle itself and can be read only once it is installed. A dry run therefore cannot show the requirements of a bundle that would be installed: those bundles are listed in data.requirementsAfterInstall, and the real run can still end with unmet prerequisites (for example Python) that the plan does not show.

For a bundle that would be updated, requirements are read from the version installed today, not from the new one (each requirement carries readFromVersion).
Licenses of bundles that are not installed yet are unknown (warning LICENSES_UNKNOWN_BEFORE_INSTALL).
Versions to install come from the online index (warning ONLINE_INDEX_UNREACHABLE when it cannot be read).
With --dry-run, data.mode is DRY_RUN, each entry of data.bundles[] is INSTALL, UPDATE, KEEP or UNKNOWN, and data.applyCommand is the command that applies the plan.
Every command that setup and doctor print (applyCommand, the --fix command, the VS Code commands) is safe to copy and paste in PowerShell, cmd, bash and zsh: each path and profile name is in double quotes, spaces and Chinese, Japanese or Korean characters included. A value that a shell would interpret inside double quotes (a double quote, $, a backtick, %, !, a line break, a trailing backslash, or consecutive backslashes such as a UNC path) is never written wrongly: the command is left out and the next step says to run the same command yourself.

Example:

cube agentic-ai setup --dry-run
cube agentic-ai setup --project-folder ~/work/my-board
cube agentic-ai setup --contexts cube-agentic-ai-st-docs,cube-agentic-ai-sidekick-kb --project-folder ~/work/my-board

doctor¶

Check the requirements that the installed contexts declare: tools, Cube bundles, Python packages, extensions. Use it when an issue arises, or to verify an installation.

cube agentic-ai doctor [<project_top_folder>] [options]

Argument / option	Default	Description
`project_top_folder`	machine scope	Check the contexts and services deployed in this project. Omit it to check the contexts installed on the machine, with all their services.
`--bundles <bundle,...>`	all	Check only these catalog bundles.
`--fix`	off	Resolve the unmet dependencies, then check again.
`--vscode-profile <name>`	the Default profile	VS Code profile of the project, one at most, written in the extension commands of `data.vscodeProfile`. The exact name is used; invalid names are refused (`INVALID_VSCODE_PROFILE_NAME`).

Requirement kinds:

prerequisite: something the user must ensure. The installer reports its remediation text and link but never acts on it.
dependency: something the installer can resolve. --fix resolves it, unless an unmet prerequisite of the same services blocks it.

Statuses: satisfied, unmet, manual (check by hand), unknown (the check could not run). Read-only extension checks are manual and carry extensionId. With --fix --vscode-profile "<name>", successful verification/installation makes them satisfied for that invocation; failed installations are unmet, while an unavailable profile or code leaves them unknown. A subsequent read-only run returns extension checks to manual because it does not inspect the active window.

Doctor starts with an activity line on stderr, before checking the contexts. Progress and diagnostics never go to stdout. stdout remains JSON-only. Pass --verbose none to suppress stderr progress and diagnostics explicitly.

Outcome:

Returns: data.readiness, data.contexts[].requirements[], data.blockedServices[] (services that cannot work because of an unmet requirement), data.skipped[] (contexts not checked, with the reason: NOT_INSTALLED, NOT_DEPLOYED, BUNDLE_VERSION_NOT_PRESENT_ON_MACHINE or AI_METADATA_INVALID), data.warnings[], data.nextSteps[], and data.fixes[] with --fix.
Skipped contexts: a skipped context is not known to be fine, so data.readiness is ACTION_REQUIRED while one is skipped. The only exception is a catalog context that is not installed when the whole machine is checked without --bundles, which is a choice (setup --contexts). For NOT_DEPLOYED, data.nextSteps gives project-add and doctor --fix commands for this folder and preserves the target recorded by another deployed context when available. BUNDLE_VERSION_NOT_PRESENT_ON_MACHINE is an error: the version deployed in the project is not installed on the machine (it was removed), so the scripts and the catalog that its services need may be missing and it cannot be checked. The entry carries deployedVersion and, when one is installed, installedVersion; its next step starts with ERROR and offers two ways out: restore the exact version with cube bundle install <bundle>@<deployed version>, or replace it with the latest installed one, project-remove then project-add <bundle>@<installed version> --services all; either way followed by doctor <project_top_folder> --bundles <bundle> --fix, because neither command resolves requirements (a restored ESW version, for example, has lost its Python environment).
No deployed contexts: when the project has never been deployed, doctor suggests setup. If it has a services lock left after its contexts were removed, setup refuses it. The field data.nextSteps says so and suggests adding a context with project-add <bundle> <project_top_folder> using the intended target, then running doctor --fix.
Not on the latest version: several versions of a bundle can coexist on a machine. When the version deployed in the project is installed but a newer one is installed too, the context is checked as usual, carries the warning NOT_LATEST_MACHINE_VERSION and latestInstalledVersion, and a next step gives the same replacement commands, ending with the doctor --fix command. It is a notice, not an error. setup never moves a deployed context by itself.
VS Code extensions: data.vscodeProfile gives verify/install/open commands for the named profile, or Default when omitted. With --fix and an explicit profile, doctor runs verification and installs missing dependency extensions automatically. data.vscodeInstall reports the profile result (PROCESSED, PROFILE_UNAVAILABLE, or CODE_FAILED) and each extension (INSTALLED, ALREADY_INSTALLED, or FAILED); matching data.fixes[] entries carry type: "vscode-extension" and the status afterwards. It never creates a profile, uses --force, opens a window, or reloads VS Code. Without an explicit profile, extensions stay manual even with --fix; run the returned commands manually if desired. Reload the VS Code window after installation.
Exit code: 0 whenever the diagnosis ran, including with unmet requirements. A failure to run it returns ok: false.
Machine level: read-only without --fix. With --fix, installs Cube bundles (never recorded in a project lock) and runs declared resolutions. With an explicit --vscode-profile, it also installs declared extension dependencies in that profile. A project-scoped Python choice needs a project folder. Use project-scope doctor for that dependency. Without a project folder, that check is unknown, not a claim that Python packages are missing.
Project level: read-only without --fix. With --fix, it applies only declared dependency resolutions. An ESW resolution can write its Python choice under that project’s .cube-ai/esw-python/. It does not deploy contexts or change project locks.

Example:

cube agentic-ai doctor ~/work/my-board
cube agentic-ai doctor ~/work/my-board --bundles cube-agentic-ai-esw --fix
cube agentic-ai doctor ~/work/my-board --vscode-profile "STM32 dev"
cube agentic-ai doctor ~/work/my-board --vscode-profile "STM32 dev" --fix

machine-bootstrap¶

Install all STM32Cube Agentic Context bundles supported by the installer on the machine. Any required Cube tool dependency bundles are installed automatically by the cube bundle manager.

Scope note:

--upgrade-installed-in-range applies to installer-catalog context bundles only.
Transitive tool dependency bundles are resolved and installed by the cube bundle manager according to its standard dependency resolution policy.

cube agentic-ai machine-bootstrap [options]

Option	Default	Description
`--dry-run`	off	Report what would be installed without installing
`--upgrade-installed-in-range true\|false`	`false`	When `true`, also upgrades already installed in-scope bundles if a newer eligible version is available. When `false`, keeps the default behavior: install missing bundles and fix non-compliant installed bundles, without proactively upgrading already-compliant ones.

Outcome:

Returns: command-level data.status, plus per-bundle status (WOULD_INSTALL, WOULD_UPDATE, ALREADY_INSTALLED, INSTALLED, UPDATED, or FAILED) in data.results[] for every context in the set.
Partial failure: if at least one context is installed, updated, already installed, or would be installed/updated, the command returns ok: true, data.status: "PARTIAL", and any failed context is reported as status: "FAILED" in data.results[] with a reason.
All failed: if every processed context fails, the command returns ok: false with error.code: "ALL_BUNDLES_FAILED". Per-bundle failure details are available in error.details.results.
Machine level: context bundles are installed, kept as-is, or updated. Required tool dependencies are resolved and installed by the cube bundle manager.
Project level: none.
Requirements: not checked or resolved. Use setup, or run doctor --fix after the deployment.

Boolean value handling:

For --upgrade-installed-in-range [true|false], accepted values are case-insensitive: true, false, 1, 0, yes, no, y, n.
If --upgrade-installed-in-range is provided without a value, it is interpreted as true.

Command status codes (in data.status):

Status code	Meaning
`ALL_DEPLOYED`	Every processed context was installed, updated, or already installed.
`PARTIAL`	At least one context succeeded and at least one context failed. Inspect `data.results[]`.
`NONE_DEPLOYED`	No context was processed, for example because the catalog was empty.
`DRY_RUN`	`--dry-run` is on; no install or update was performed. Inspect `data.results[]` for the planned per-bundle outcome.

Per-bundle status codes (in each data.results[] entry’s status field):

Status code	Meaning
`INSTALLED`	Bundle was not present and has been successfully installed.
`UPDATED`	Bundle was already present and has been upgraded to a newer eligible version.
`ALREADY_INSTALLED`	Bundle was already present on the machine; nothing changed.
`WOULD_INSTALL`	`--dry-run` is on; bundle would be installed but was not.
`WOULD_UPDATE`	`--dry-run` is on; bundle would be upgraded/remediated but was not.
`FAILED`	Installation attempt failed. A `reason` field accompanies the entry with the error detail.

Idempotency and version update behaviour

machine-bootstrap behavior depends on the catalog versionSpec and on --upgrade-installed-in-range:

Catalog `versionSpec`	Matching rule	Action when `--upgrade-installed-in-range=false`	Action when `--upgrade-installed-in-range=true`
absent	any installed version accepted	Missing bundles are installed. Already-installed bundles are left unchanged.	Missing bundles are installed. Already-installed bundles can be upgraded when a newer eligible version is available.
exact `1.2.3`	must match exactly	Missing or non-compliant bundles are moved to `1.2.3`.	Same as `false`.
range `^1.1.0`	must satisfy the range	Missing or non-compliant bundles are moved to a compliant version.	Missing or non-compliant bundles are moved to a compliant version; already-installed compliant bundles can be upgraded to a newer eligible version.

The command remains machine-scoped and idempotent for repeated runs with the same options and unchanged bundle availability.

Idempotency by situation:

Situation	Outcome
All catalog contexts already installed at a version satisfying their spec	All `ALREADY_INSTALLED` (unless `--upgrade-installed-in-range=true` and a newer eligible version is available).
Newer within-range version available on server; installed version still satisfies spec; `--upgrade-installed-in-range=false`	`ALREADY_INSTALLED`. No change is applied.
Newer within-range version available on server; installed version still satisfies spec; `--upgrade-installed-in-range=true`	`UPDATED`. Highest eligible online version is installed.
Installed version does NOT satisfy the spec (range raised, exact version changed)	The bundle is moved to a compliant version; reported as `UPDATED` if it already existed, otherwise `INSTALLED` (dry-run: `WOULD_UPDATE` or `WOULD_INSTALL` respectively).
New contexts added to the catalog	New entries `INSTALLED`; existing entries `ALREADY_INSTALLED` or `UPDATED` depending on flag and available eligible versions.

machine-install¶

Install one STM32Cube Agentic Context bundle on the machine. The installer verifies that the bundle is supported before proceeding. To install another kind of bundle, use cube bundle install directly.

If the context requires a STM32Cube tool delivered as a bundle, the cube bundle manager installs that tool dependency automatically — no separate install command is needed.

cube agentic-ai machine-install <bundle_name>

Argument	Description
`bundle_name`	Context bundle identifier, for example `cube-agentic-ai-esw` or `cube-agentic-ai-esw@<version>`

Outcome:

Returns: install status and resolved context bundle version.
Machine level: the context bundle is installed or reused. Required Cube tool dependencies are installed by cube.
Project level: none.
Requirements: not checked or resolved. Use setup, or run doctor --fix after the deployment.

machine-discovery¶

Show what is currently installed on the machine. Context bundles installed through this installer are marked IN_SCOPE. Tool dependency bundles required directly by installed contexts are marked DIRECT_AI_DEPENDENCY. All remaining bundles are marked OUT_OF_SCOPE.

cube agentic-ai machine-discovery [options]

Option	Default	Description
`--json`	on	Generate a machine catalog JSON file in addition to stdout command JSON
`--no-json`	off	Disable machine catalog JSON file generation
`--ai-only`	off	Exclude `OUT_OF_SCOPE` bundles from stdout result and generated catalog file
`--json-file <path>`	`machine-catalog.json`	Output path for the generated machine catalog JSON file

Outcome:

Returns: command-result JSON on stdout with discovered bundles (name, version, category). Category values are IN_SCOPE, DIRECT_AI_DEPENDENCY, or OUT_OF_SCOPE.
Generated file: when --json is enabled (default), writes a JSON file containing only the bundle list array (no command envelope fields like ok or error).
Validation: passing --json-file together with --no-json fails with a structured option-combination error.
Environment scope: discovery uses CUBE_BUNDLE_PATH as the machine root and intentionally ignores CUBE_BUNDLE_PATH_EXTRA for listing and metadata classification.
Machine level: none (read-only).
Project level: none.

Machine-discovery error codes:

Error code	Meaning
`INVALID_OPTION_COMBINATION`	`--json-file` was passed while `--no-json` disabled file generation.
`INVALID_USAGE`	`--json-file` is empty while JSON file generation is enabled.
`CATALOG_NOT_FOUND`	Context catalog file is missing.
`CATALOG_PARSE_ERROR`	Context catalog file is not valid JSON.
`CATALOG_INVALID`	Context catalog fails schema validation.
`CUBE_LIST_ERROR`	`cube bundle list` failed while reading machine inventory.
`CUBE_BUNDLE_INFO_ERROR`	Failed to read installed context metadata for direct dependency classification.
`JSON_FILE_WRITE_FAILED`	Machine catalog JSON output file could not be created or written.
`MACHINE_DISCOVERY_FAILED`	Unexpected machine-discovery failure not covered by a specific typed error code.

show-catalog¶

Display the installer context catalog to discover which STM32Cube Agentic Context bundles it supports.

Purpose note:

This command reads the catalog bundled with the installer. It does not query the online registry.

cube agentic-ai show-catalog [options]

Option	Default	Description
`--short true\|false`	`true`	`true`: return compact items (`bundleName`, `description`). `false`: return full catalog entries.

Boolean value handling:

For --short [true|false], accepted values are case-insensitive: true, false, 1, 0, yes, no, y, n.
If --short is provided without a value, it is interpreted as true.

Outcome:

Returns: command-result JSON on stdout with data.short and data.items.
Machine level: none (read-only).
Project level: none.

Prerequisites:

cube must be installed and on PATH.
The installer bundle’s local catalog must be available. No network connectivity is required.

Show-catalog error codes:

Error code	Meaning
`CATALOG_NOT_FOUND`	Context catalog file is missing.
`CATALOG_PARSE_ERROR`	Context catalog file is not valid JSON.
`CATALOG_INVALID`	Context catalog fails schema validation.
`SHOW_CATALOG_FAILED`	Unexpected show-catalog failure not covered by a specific typed error code.

list-supported-targets¶

Display the deployment targets supported by this installer release, that is the accepted values of the --ide and --agentic-system options used by the project commands.

cube agentic-ai list-supported-targets

This command takes no option.

Outcome:

Returns: command-result JSON on stdout with data.ides, data.agenticSystems, data.defaults and data.canonical.
Machine level: none (read-only).
Project level: none.

Each entry of data.ides and data.agenticSystems carries the id to pass to the option and a human-readable label. data.defaults reports the values applied when the option is omitted.

data.canonical documents the --canonical option: instead of the native layout selected by --ide and --agentic-system, --canonical deploys a generic folder structure under the canonical root folder (.cube-ai/). The agentic system in use can then reshuffle that structure per its own needs.

Values are read from the installer deployment-targets catalog. A target appears only when it is marked supported for the release. This release supports the IDE targets vscode and none, and the agentic-system targets github-copilot and claude-code. To use Claude Code without an IDE binding, pass --ide none --agentic-system claude-code.

List-supported-targets error codes:

Error code	Meaning
`CATALOG_VALIDATION_FAILED`	Target matrix catalog is missing or fails schema validation.
`NO_SUPPORTED_TARGET`	Target matrix catalog flags no supported IDE or agentic-system target.
`LIST_SUPPORTED_TARGETS_FAILED`	Unexpected failure not covered by a specific typed error code.

project-add¶

Add one STM32Cube Agentic Context bundle to a project: installs it on the machine if needed, then deploys its files into the project folder and assembles the routing file.

cube agentic-ai project-add <bundle_name> <project_top_folder> [options]

Argument	Description
`bundle_name`	Context bundle reference: `cube-agentic-ai-<connector>`, `cube-agentic-ai-<connector>@<version>`, or an explicit semver range after `@`
`project_top_folder`	Absolute or relative path to the project top folder

Option	Default	Description
`--services <id,...>`	—	Deploy only the listed service IDs (plus required ones). Special value: `all` (deploy all services). Empty value is rejected.
`--interactive [true\|false]`	false	Prompt for service selection when `--services` is omitted. Ignored when `--services` is provided. If `--interactive` is omitted, default and required services are deployed. Interactive prompts are written to stdout before the final command result, so this mode is intended for human terminal sessions rather than JSON-only stdout parsing. In prompts, `y` and `yes` are equivalent and case-insensitive; pressing Enter applies the displayed default.
`--ide <id\|none\|other>`	`vscode`	IDE target for artifact placement
`--agentic-system <id>`	`github-copilot`	Agentic system target
`--canonical`	off	Force deployment under `.cube-ai/` only; overrides `--ide` and `--agentic-system` placement
`--autodetect-targets off\|advisory\|enforce`	`off`	Detect IDE and agentic system from the project environment. `advisory`: when `--ide` or `--agentic-system` is missing, return detected candidates as an expected advisory-only result and stop before deployment. `enforce`: apply detected values for any target not set explicitly, or fail on ambiguity. Explicit `--ide`/`--agentic-system` flags always take precedence over detection.
`--bundle-version-policy flexible\|lock-driven`	`flexible`	Version-resolution policy for unpinned `bundle_name` (`name` without `@version`). `flexible`: reuse the highest installed semantic version. `lock-driven`: reuse project-locked version when available; fail with `BUNDLE_LOCKED_VERSION_NOT_INSTALLED` if that locked version is not installed locally. Explicit pinned `name@version` remains authoritative.
`--routing-mode <mode>`	`usage-router`	Routing catalog assembly mode. `usage-router`: legacy catalog plus second-choice guidance when at least two services are installed, without overlap arbitration. `usage-router-with-arbitration`: add policy-driven arbitration when context responsibilities overlap.

Boolean value handling:

For --interactive [true|false], accepted values are case-insensitive: true, false, 1, 0, yes, no, y, n.
If --interactive is provided without a value, it is interpreted as true.

Outcome:

Returns: deployment result with selected services, artifact paths, and deployment layout status.
Advisory mode: when --autodetect-targets advisory stops early, the JSON result uses status: ADVISORY_ONLY and installStatus: SKIPPED and does not install or deploy anything.
Machine level: bundle installed if not already present.
Version selection is based on the CLI bundle_name reference passed to project-add (name, name@version, or name@<semver range>). An explicit reference is honored.
If bundle_name is unpinned (no @ reference), the command reuses the highest installed semantic version for that bundle name.
An unpinned project-add <bundle> intentionally does not enforce installer-catalog versionSpec ranges, so it can select any installed version. Use an explicit name@<semver range> when the catalog constraint must be respected, including after a failed setup installation.
Under lock-driven, unpinned project-add <name> uses the version already locked in the project when available. If that locked version is no longer installed locally, the command fails with BUNDLE_LOCKED_VERSION_NOT_INSTALLED.
Explicit pinned references (name@version) remain authoritative and bypass policy fallback.
Project level: deployment folder updated, project lock updated, routing catalog regenerated, and mcp.json merged.
Requirements: not checked or resolved: the Python packages, tool bundles and VS Code extensions that the context declares are not installed. Run cube agentic-ai doctor <project_top_folder> --bundles <bundle_name> --fix afterwards.
Idempotency note: idempotency is guaranteed only for repeated successful executions with identical inputs. After any failure or partial execution, the command resumes from the current state and may apply changes on top of existing artifacts.

Machine install status codes (in data.installStatus):

Status code	Meaning
`INSTALLED`	Bundle was not present and has been installed as part of this command.
`REUSED`	A satisfying version was already installed; no install was performed.

Cube project lock status codes (in data.cubeProjectLockStatus):

Status code	Meaning
`RECORDED`	Bundle reference recorded in `.settings/bundles.store.json`; `bundleVersion` is the version resolved there.
`EXCLUDED`	Bundle listed in `cube-project-lock-exclusions.json` (today only `cube-agentic-ai-installer`); tracked only in `services-lock.json` with the installed version.

See Lock files for the rationale.

Tool dependency output (in data.dependencies):

Each entry reports the dependency name, locked version (omitted when removed), lockStatus (ADDED, UPDATED, UNCHANGED, or REMOVED), and machineStatus (INSTALLED or REUSED).
previousVersion is included when the project-lock version changed or the dependency was removed.
newerInstalledVersion identifies a newer installed version that satisfies the declared range but is not selected by the project lock. The command remains successful and adds TOOL_DEPENDENCY_PINNED_BY_PROJECT_LOCK to data.warnings, with the refresh hint in data.warningMessages. Run cube bundle update --project from the workspace when you intend to refresh its tool dependencies.

Target resolution priority for project-add:

The effective --ide, --agentic-system, and --canonical values are resolved in this strict priority order:

Priority	Source	Condition
1 (highest)	Explicit CLI flag	Flag was passed on the command line. Always wins.
2	Autodetection	`--autodetect-targets enforce` is set and the dimension was not resolved by a CLI flag. When `advisory`, detected candidates are reported but not applied.
3 (lowest)	ST default	No CLI flag or autodetection result resolved the dimension. Defaults: `--ide vscode`, `--agentic-system github-copilot`, `--canonical` off.

Canonical layout interaction:

--canonical is orthogonal to --ide and --agentic-system. When --canonical is specified:

Target resolution still runs for --ide and --agentic-system (following the priority above).
After resolution, --canonical overrides the deployment family: all artifacts are written under .cube-ai/ regardless of the resolved IDE and agentic system values.
Target specific host folders such as .github/skills/ or .vscode/ are not created or updated for deployed artifacts.
The services lock records ide: none and agenticSystem: none to reflect that no native placement was performed.

For the full list of --ide/--agentic-system pairings and file placement rules, see Target selection.

Deployment layout status codes (in data.deploymentLayout.status):

Status code	Meaning
`PLACED_BY_INSTALLER`	Artifacts were placed directly in the locations expected by the selected IDE and agentic system. No further action required.
`AGENT_RESHUFFLE_REQUIRED`	`--canonical` was used: artifacts were placed in the portable `.cube-ai/` layout instead of the native locations. The agentic system must reorganize them to match its own recommended folder structure before use. The `reshuffleHint` field in the response provides guidance. If files are moved after deployment, `project-remove` still uses the canonical paths recorded in the lock and moved files may require manual cleanup.

Status code

Meaning

PLACED_BY_INSTALLER

Artifacts were placed directly in the locations expected by the selected IDE and agentic system. No further action required.

AGENT_RESHUFFLE_REQUIRED

--canonical was used: artifacts were placed in the portable .cube-ai/ layout instead of the native locations. The agentic system must reorganize them to match its own recommended folder structure before use. The reshuffleHint field in the response provides guidance. If files are moved after deployment, project-remove still uses the canonical paths recorded in the lock and moved files may require manual cleanup.

project-deploy¶

Deploy supported STM32Cube Agentic Context bundles into a project in one pass.

cube agentic-ai project-deploy <project_top_folder> [options]

Argument	Description
`project_top_folder`	Absolute or relative path to the project top folder

Option	Default	Description
`--mode interactive\|all`	`interactive`	Propose bundles one by one, or deploy all at once. Implicitly `all` when `--preset` is provided. Interactive prompts are written to stdout before the final command result, so this mode is intended for human terminal sessions rather than JSON-only stdout parsing.
`--preset <config_file>`	—	Path to a JSON preset file that specifies exact context bundle versions and service provenance. Accepts the output of `project-lock-show` directly. When provided, interactive prompts and `--services-mode` are suppressed.
`--preset-no-reconcile`	off	Exact preset replay mode. Valid only with `--preset`: groups context services by provenance version and dispatches one pinned deployment per version group. When used without `--preset`, command fails with `PROJECT_DEPLOY_INVALID_OPTIONS`.
`--auto-install-missing true\|false`	`true`	Install missing bundles automatically as prerequisites
`--services-mode default\|all\|interactive`	`default`	Service selection strategy. Ignored when `--preset` is provided.
`--ide <id\|none\|other>`	`vscode`	IDE target
`--agentic-system <id>`	`github-copilot`	Agentic system target
`--canonical`	off	Force canonical deployment layout; overrides `--ide` and `--agentic-system` placement
`--autodetect-targets off\|advisory\|enforce`	`off`	Detect IDE and agentic system from the project environment. `advisory`: report suggestions only. `enforce`: apply detected values for any target not set explicitly. Explicit `--ide`/`--agentic-system` flags always take precedence over detection.
`--dry-run`	off	Report what would be deployed without deploying
`--bundle-version-policy flexible\|lock-driven`	`flexible`	Forwarded to child `project-add` calls. In non-preset mode, `lock-driven` reuses project-locked versions when available and falls back to `flexible` for first introduction of a bundle. In preset mode, bundle references are already pinned (`name@version`) and are authoritative over the policy.
`--routing-mode <mode>`	`usage-router`	Forwarded unchanged to each child `project-add` call. See the `project-add` option table for the meaning of each value.

Boolean value handling:

For --auto-install-missing [true|false], accepted values are case-insensitive: true, false, 1, 0, yes, no, y, n.
If --auto-install-missing is provided without a value, it is interpreted as true.

Interactive yes/no handling (--mode interactive):

Each bundle prompt is interpreted as: Enter = yes (default), y/yes = yes, any other non-empty answer = no.
Parsing is case-insensitive.
Prompts are handled through stdin/stdout and are printed before the final result JSON. Callers that need machine-readable stdout must combine --mode all with --services-mode default or --services-mode all, or use --preset.

Bundle version input model for project-deploy:

This command has no positional <bundle_name> argument.
Without --preset, bundle names and optional version specs come from the installer context catalog.
With --preset, each bundle entry carries an exact pinned version (name + version) from the preset file.

Outcome:

Returns: full deployment summary with per-bundle service selections, artifact paths, and deployment layout status.
Machine level: missing context bundles are installed if --auto-install-missing is on. Required tool dependency bundles are installed by cube.
Version-selection behavior:
- In non-preset mode, per-bundle deployment is executed through project-add using bundle name references from the installer catalog. This intentionally does not enforce catalog versionSpec during deployment, so users can deploy newer bundle versions even when the local installer catalog is outdated.
- As a consequence, when multiple versions are installed and no exact version is pinned in the effective bundle reference passed to project-add, the highest installed semantic version for that bundle name is reused.
- In preset mode, the exact version declared in the preset entry is used (name@version) and is authoritative.
- project-deploy forwards --bundle-version-policy to child project-add calls.
- With --bundle-version-policy lock-driven in non-preset mode, bundles already present in project lock are replayed with their locked version; bundles not yet in project lock fall back to flexible for first introduction.
Project level: deployment folder updated, project lock updated, routing catalog regenerated, and mcp.json merged.
Requirements: not checked or resolved, for any deployed context. Run cube agentic-ai doctor <project_top_folder> --fix afterwards.
Idempotency note: idempotency is guaranteed only for repeated successful executions with identical inputs. After any failure or partial execution, the command resumes from the current state and may apply changes on top of existing artifacts.

Routing-authority output fields:

When ok: true, data.hostInstructionUpdate provides a post-deploy action payload that helps enforce authoritative routing behavior in the host agentic system:

Field	Type	Description
`data.hostInstructionUpdate.requiredStatement`	string	Mandatory statement to place in host instructions so the `cube-agentic-ai-routing` skill is invoked before planning and its generated catalog selects the applicable connector skills and MCP servers.
`data.hostInstructionUpdate.callToAction`	string	Explicit action message requesting to add the mandatory statement to the host instruction file.

Target resolution with --preset:

The effective --ide, --agentic-system, and --canonical values are resolved in this strict priority order for every project-deploy invocation, whether or not --preset is used:

Priority	Source	Condition
1 (highest)	Explicit CLI flag	Flag was passed on the command line. Always wins.
2	Preset file field	`--preset` was provided and the preset contains the corresponding top-level field (`ide`, `agentic-system`, or `canonical`). Only used when the CLI flag was not passed.
3	Autodetection	`--autodetect-targets enforce` is set and the dimension was not resolved by a CLI flag or preset field. When `advisory`, detected candidates are reported but not applied.
4 (lowest)	ST default	No CLI flag, preset field, or autodetection result resolved the dimension. Defaults: `--ide vscode`, `--agentic-system github-copilot`, `--canonical` off.

Examples:

--ide none passed + preset has "ide": "vscode" → effective IDE is none (CLI wins).
No --ide passed + preset has "ide": "none" → effective IDE is none (preset fallback).
No --ide passed + preset has no ide field → effective IDE is vscode (ST default).
--ide none passed + no preset → effective IDE is none (CLI wins, ST default for others).

Canonical layout interaction:

--canonical is orthogonal to --ide and --agentic-system. When --canonical is specified (via CLI or preset):

Target resolution still runs for --ide and --agentic-system (following the priority above).
After resolution, --canonical overrides the deployment family: all artifacts are written under .cube-ai/ regardless of the resolved IDE and agentic system values.
Target specific host folders such as .github/skills/ or .vscode/ are not created or updated for deployed artifacts.
The services lock records ide: none and agenticSystem: none to reflect that no native placement was performed.
--canonical in a preset can be overridden by passing --canonical explicitly on the CLI (CLI priority 1 always wins).

For the full list of --ide/--agentic-system pairings and file placement rules, see Target selection.

Output ok field and partial success:

ok: true does not mean every bundle succeeded. The command continues after a per-bundle failure so that other bundles are not blocked. Check data.status and inspect data.bundles[].outcome to know the result for each bundle:

`data.status`	`ok`	Meaning
`ALL_DEPLOYED`	`true`	Every accepted bundle was deployed successfully.
`PARTIAL`	`true`	At least one bundle succeeded and at least one failed. Partially deployed bundles remain in the project.
`NONE_DEPLOYED`	`true`	No bundles were accepted (all rejected interactively, or the catalog/preset contained no contexts).
`DRY_RUN`	`true`	`--dry-run` was active; no mutations were performed.
—	`false`	Command-level failure (bad project root, catalog unavailable, preset invalid) that prevented any bundle from being attempted.

When ok: true and status: PARTIAL, each failed bundle has outcome: "FAILED" and an error object in its data.bundles[] entry.

Deployment warning output:

data.warnings contains warning codes propagated from child project-add operations, such as lock-consistency warnings.
TOOL_DEPENDENCY_PINNED_BY_PROJECT_LOCK means a newer compatible installed tool dependency is not selected because the project lock preserves its current version.
Each successful data.bundles[] entry exposes the same dependency array under detail.dependencies.
data.warningMessages contains human-readable, non-fatal deployment warnings. It is omitted when there are no such warnings.
If every attempted bundle fails, warning messages discovered during candidate resolution are returned under error.details.warningMessages instead.
When present, these fields are included in the JSON result regardless of --verbose. With --verbose standard or --verbose debug, warning messages are also written to stderr.

For project-deploy-installed, installed-inventory resolution detects catalog entries marked required that have no eligible installed version. The command returns each missing bundle in a human-readable data.warningMessages entry, but leaves it out of the candidate set and does not install it. The warning explains that installed-only behavior is being honored. Run machine-bootstrap to install catalog bundles, then rerun project-deploy-installed when appropriate. This warning does not change candidate selection or make the command fail.

project-deploy-installed¶

Deploy into a project using only bundles already installed on the machine as the candidate set. Use this command when you have deliberately installed exactly the bundles you want (via machine-bootstrap or machine-install) and want to deploy only those — nothing more, nothing less. Unlike project-deploy, which proposes from the full supported set, this command is driven entirely by your machine inventory, so there are no unexpected bundles and no automatic installs.

cube agentic-ai project-deploy-installed <project_top_folder> [options]

Argument	Description
`project_top_folder`	Absolute or relative path to the project top folder

Option	Default	Description
`--mode interactive\|all`	`interactive`	Propose candidates one by one, or deploy all
`--services-mode default\|all\|interactive`	`default`	Service selection strategy applied per selected bundle
`--ide <id\|none\|other>`	`vscode`	IDE target
`--agentic-system <id>`	`github-copilot`	Agentic system target
`--canonical`	off	Force canonical deployment layout; overrides `--ide` and `--agentic-system` placement
`--autodetect-targets off\|advisory\|enforce`	`off`	Detect IDE and agentic system from the project environment. `advisory`: report suggestions only. `enforce`: apply detected values for any target not set explicitly. Explicit `--ide`/`--agentic-system` flags always take precedence over detection.
`--dry-run`	off	Report what would be deployed without deploying
`--routing-mode <mode>`	`usage-router`	Forwarded unchanged to each child `project-add` call. See the `project-add` option table for the meaning of each value.

Out-of-scope bundles discovered on the machine are never deployment candidates for this command.

Target resolution priority for project-deploy-installed:

The effective --ide, --agentic-system, and --canonical values are resolved in this strict priority order:

Priority	Source	Condition
1 (highest)	Explicit CLI flag	Flag was passed on the command line. Always wins.
2	Autodetection	`--autodetect-targets enforce` is set and the dimension was not resolved by a CLI flag. When `advisory`, detected candidates are reported but not applied.
3 (lowest)	ST default	No CLI flag or autodetection result resolved the dimension. Defaults: `--ide vscode`, `--agentic-system github-copilot`, `--canonical` off.

Canonical layout interaction:

--canonical is orthogonal to --ide and --agentic-system. When --canonical is specified:

Target resolution still runs for --ide and --agentic-system (following the priority above).
After resolution, --canonical overrides the deployment family: all artifacts are written under .cube-ai/ regardless of the resolved IDE and agentic system values.
The services lock records ide: none and agenticSystem: none to reflect that no native placement was performed.

For the full list of --ide/--agentic-system pairings and file placement rules, see Target selection.

project-deploy-installed has no --preset option. The only sources for target resolution are CLI flags, autodetection, and ST defaults (no preset field can override a CLI flag here).

Selection behavior:

--mode controls bundle candidate selection (interactive prompts per bundle, all accepts all candidates).
--services-mode controls per-bundle service selection (default, all, interactive).
When the bundle reference does not pin an exact version and several installed versions of the same bundle are eligible, the highest installed semantic version is selected for deployment.
This command is effectively pinned by construction (name@version candidates), so it does not expose --bundle-version-policy.

Outcome:

Returns: deployment summary with per-bundle service selections, artifact paths, and deployment layout status.
Successful bundle details include detail.dependencies with project-lock and machine-install statuses for transitive tool dependencies.
A newer compatible installed version that is not used because of the project lock adds TOOL_DEPENDENCY_PINNED_BY_PROJECT_LOCK to data.warnings. Deployment remains successful.
Machine level: none (no bundle install).
Project level: deployment folder updated, project lock updated, routing catalog regenerated, and mcp.json merged.
Requirements: not checked or resolved, for any deployed context. Run cube agentic-ai doctor <project_top_folder> --fix afterwards.
Idempotency note: idempotency is guaranteed only for repeated successful executions with identical inputs. After any failure or partial execution, the command resumes from the current state and may apply changes on top of existing artifacts.

Routing-authority output fields:

When ok: true, data.hostInstructionUpdate provides the same post-deploy action payload as project-deploy:

Field	Type	Description
`data.hostInstructionUpdate.requiredStatement`	string	Mandatory statement to place in host instructions so the `cube-agentic-ai-routing` skill is invoked before planning and its generated catalog selects the applicable connector skills and MCP servers.
`data.hostInstructionUpdate.callToAction`	string	Explicit action message requesting to add the mandatory statement to the host instruction file.

project-lock-show¶

Display the current project lock state, including deployed context bundle versions, selected services, and the exact versions of required tool dependency bundles.

The command output is machine-readable JSON and is a valid preset file for project-deploy --preset. It captures context bundle versions and resolved tool dependency bundle versions so the same environment can be replayed on another machine or project.

cube agentic-ai project-lock-show <project_top_folder>

Argument	Description
`project_top_folder`	Absolute or relative path to the project top folder

Outcome:

Returns: machine-readable lock state including context bundle versions, resolved tool dependency bundle versions, selected services, deployment target per bundle, and managed file ownership records.
Machine level: none (read-only).
Project level: none.
State model: reports the current merged state per bundle from services-lock.json. If project-add or project-deploy is run multiple times for the same bundle with different service selections, all selected services remain listed until removed by project-remove.
Warnings and integrity: when consistency issues are detected (for example context version drift between locks), output remains ok: true and includes warning information. If present, services-lock.json.integrity is also reported so automation can detect degraded lock reliability.
Warning field location: warnings are emitted in the command stdout JSON success payload under data.warnings.

project-remove¶

Remove one deployed STM32Cube Agentic Context bundle from a project, reverting the effect of project-add.

cube agentic-ai project-remove <bundle_name> <project_top_folder> [options]

Argument	Description
`bundle_name`	Context bundle identifier to remove from the project
`project_top_folder`	Absolute or relative path to the project top folder

Option	Default	Description
`--services <id,...>`	—	Remove only the listed service IDs. If omitted, all deployed services of the bundle are removed.
`--confirm-always`	off	Bypass the confirmation prompt when removing a required service while other services from the same context remain. Not needed when removing the whole bundle or all deployed services.
`--dry-run`	off	Report what would be removed without removing anything
`--routing-mode <mode>`	`usage-router`	Routing catalog assembly mode used when regenerating the routing catalog after removal. See the `project-add` option table for the meaning of each value.

Outcome:

Returns: list of removed files, updated lock paths, and remaining deployed services (if partial removal).
Machine level: none (bundle remains installed on the machine).
Project level: selected deployment files removed, project lock updated, routing catalog regenerated.

Project-remove error codes:

Error code	Meaning
`BUNDLE_NOT_DEPLOYED`	The requested bundle has no entry in `.cube-ai/services-lock.json` for this project.
`SERVICES_VALIDATION_FAILED`	`--services` is empty or includes service IDs not currently deployed for this bundle.
`PROJECT_REMOVE_REQUIRED_SERVICE_CONFIRMATION_REQUIRED`	A partial removal includes a service recorded with the `\|required` provenance tag; rerun with `--confirm-always` or confirm the interactive prompt.
`PROJECT_REMOVE_MANAGED_PATHS_MISSING`	One or more managed artifact paths are missing from lock metadata or missing on disk during remove preflight.
`PROJECT_REMOVE_PERMISSION_PRECHECK_FAILED`	One or more managed artifact paths cannot be removed due to filesystem permission checks.
`PROJECT_REMOVE_IO_FAILED`	Deletion failed during the remove commit phase after preflight succeeded.
`SERVICES_LOCK_UNRELIABLE_WRITE_FAILED`	After partial deletion failure, writing degraded-state marker (`integrity.state = UNRELIABLE`) to services lock failed.
`SERVICES_LOCK_READ_FAILED`	`.cube-ai/services-lock.json` is present but unreadable or invalid JSON.
`SERVICES_LOCK_WRITE_FAILED`	Writing `.cube-ai/services-lock.json` failed.
`PROJECT_REMOVE_FAILED`	Unexpected project-remove failure not covered by a more specific typed error code.

For recovery steps, see Troubleshooting → Error codes.

Behavior notes:

Removal authority: project-remove uses <project_top_folder>/.cube-ai/services-lock.json as the source of truth to determine removable services and managed files.
Required services: each selectedServiceProvenance entry in the lock ends in either |required or |optional, copied from the deployed bundle manifest. When --services would remove a required service while another service from the same context remains, the command warns that the remaining services may be impeded and requires explicit confirmation. Removing the whole bundle or all deployed services does not require this confirmation. The tag is metadata only. The installer does not store a dependency graph.
Path authority model: removal candidates are derived from lock-recorded per-service managed artifact records (managedArtifacts).
Out-of-band content: files or services added manually outside installer commands are not tracked by services-lock.json and are not removed automatically.
Requirements are kept: what setup and doctor --fix installed for the context stays, because other projects can use it: Cube bundles such as the STM32CubeMX2 application, Python packages and the ESW environment of the bundle version (removed with that version by cube bundle remove), and VS Code extensions. The project keeps its .cube-ai/esw-python/ choice files, which a later version of the context reuses, and the .vscode/extensions.json recommendations.
Canonical reshuffle caveat: if deployment was done with --canonical and files were later moved to non-canonical locations, project-remove resolves removal candidates from canonical-managed paths. Moved files may remain and require manual cleanup.
Tainted lock state: after remove-time I/O failures with partial deletion, or when lock-source drift is detected, services-lock.json may be marked tainted (integrity.state = UNRELIABLE). Subsequent mutating commands still run but emit warning information.
No manifest consistency check: the command does not validate lock-versus-bundle-manifest consistency before removal.
Project scope only: this command never uninstalls bundles from machine inventory. It only updates project deployment state.

get-user-manual¶

Access the installer user manual.

cube agentic-ai get-user-manual [--format <tldr|markdown|html>]

Option	Description
`--format tldr`	Return a concise quick reference directly in JSON (`data.content`). Default when `--format` is omitted.
`--format markdown`	Return the on-disk paths to the Markdown source files (for AI agent use)
`--format html`	Open the HTML documentation in the system default browser (for human use)

Outcome:

Returns: one of: concise TLDR content (tldr), Markdown folder path(s) (markdown), or HTML entry point path (html).
Machine level: none.
Project level: none. (--format html opens the browser as a side effect.)