Usage

Workflows ordered from full onboarding to targeted maintenance operations.
Replace <project_top_folder> with the absolute path to your project top folder.

Important behavior for all deployment commands:

  • project-add and project-deploy are additive.

  • Re-deploying a smaller service subset does not remove previously deployed services.

  • Use project-remove when you need to remove services or reset a context deployment before reapplying it.

  • project-add and project-deploy accept --bundle-version-policy flexible|lock-driven (default: flexible).

  • With --bundle-version-policy flexible, when no exact version is specified and several installed versions match, project-add and project-deploy reuse the highest installed semantic version that satisfies the requested bundle reference.

  • With --bundle-version-policy lock-driven, project-add and project-deploy reuse the version already recorded in the project lock for that bundle. For a bundle not yet locked, they fall back to flexible selection. A locked version that is missing locally causes BUNDLE_LOCKED_VERSION_NOT_INSTALLED.

  • In project-deploy --preset mode, bundle references are already pinned by the preset, so --bundle-version-policy has no operational effect.

  • project-deploy-installed does not expose --bundle-version-policy because its candidates are already pinned by construction (name@version from installed inventory).

0. Quick start: set up the toolkit in one command

Use setup for the standard journey. It installs the contexts on the machine, resolves what they need, creates the project folder, deploys into it, and reports what is left to do. Read data.nextSteps in the result. setup works only for a project folder that has never been deployed: it refuses a folder that has a services lock (SETUP_PROJECT_ALREADY_DEPLOYED). In a deployed project, use the workflows of sections 5 to 8.

# Preview first: nothing is changed. Requirements of bundles not installed yet cannot be shown.
cube agentic-ai setup --dry-run

# Install and deploy into the default folder <home>/my-agentic-ai-project
cube agentic-ai setup

# Choose the project folder, and a dedicated Python environment for the Python packages
cube agentic-ai setup --project-folder <project_top_folder> --python venv

# Install only some contexts
cube agentic-ai setup --contexts cube-agentic-ai-st-docs,cube-agentic-ai-sidekick-kb --project-folder <project_top_folder>

# Also upgrade the installed contexts that have a newer version in the catalog range
cube agentic-ai setup --upgrade-installed-in-range

# Let the installer run `code` to install the VS Code extensions that the contexts declare (VS Code target only)
cube agentic-ai setup --install-vscode-extensions --vscode-profile "My profile"

When data.readiness is not READY, or when something fails later, check the installation:

# Read-only diagnosis of the contexts deployed in the project
cube agentic-ai doctor <project_top_folder>

# Resolve the unmet dependencies, then check again
cube agentic-ai doctor <project_top_folder> --fix

The workflows below use the building blocks directly: pinned versions, selected services, presets, upgrades and removal.

2. One-shot non-interactive onboarding (CI or scripted)

# Install baseline
cube agentic-ai machine-bootstrap

# Deploy all catalog bundles without prompts, using default service selections
cube agentic-ai project-deploy <project_top_folder> --mode all --services-mode default

machine-bootstrap defaults to --upgrade-installed-in-range false: missing bundles are installed, but already-installed satisfying bundles are not proactively upgraded.

Use --upgrade-installed-in-range true when you intentionally want to refresh installed in-scope bundles to newer eligible versions as part of bootstrap:

# Install missing bundles and also upgrade already-installed in-scope bundles when eligible
cube agentic-ai machine-bootstrap --upgrade-installed-in-range true

3. Reproducible deployment from a preset file

Use a preset when you need a fully scripted, version-locked deployment (CI pipelines, team onboarding).

# preset.json pins exact context bundle versions and service provenance
# {
#   "bundles": [
#     { "name": "cube-agentic-ai-esw", "version": "<context-version>", "serviceProvenance": ["S1@<context-version>|required"], "kind": "connector" },
#     { "name": "cube-agentic-ai-st-docs", "version": "<context-version>", "serviceProvenance": ["S1@<context-version>|required"], "kind": "connector" },
#     { "name": "tool-a", "version": "<tool-version>", "kind": "tool-dependency" }
#   ]
# }

cube agentic-ai project-deploy <project_top_folder> --preset preset.json

No prompts are shown. Context service selection is derived from serviceProvenance in the preset.

Target selection in preset mode follows strict priority (CLI flag > preset field > autodetect enforce > ST default):

  • When passed, --ide, --agentic-system, and --canonical always take precedence over preset target fields.

  • When not passed, preset top-level ide, agentic-system, and canonical are used if present.

  • If neither CLI flags nor preset fields provide a dimension, --autodetect-targets enforce can resolve it. Otherwise the ST default applies (vscode, github-copilot).

# Explicit target override while using a preset
cube agentic-ai project-deploy <project_top_folder> --preset preset.json \
  --ide vscode --agentic-system github-copilot

4. Reproduce an existing project environment

Capture the exact deployment of a working project and replay it elsewhere.

# On the reference machine: export the current deployment as a preset file
cube agentic-ai project-lock-show <project_top_folder> > my-preset.json

# On the target machine (or target project): replay the recorded service versions
cube agentic-ai project-deploy <project_top_folder> --preset my-preset.json --preset-no-reconcile

Use --preset-no-reconcile when services from one context were deployed from different versions. Without that option, preset replay reconciles each context’s selected services to its preset bundle version:

cube agentic-ai project-deploy <project_top_folder> --preset my-preset.json

The output of project-lock-show is a valid preset file for project-deploy --preset.

5. Add a single context to a project

# Install the context bundle on the machine (no-op if already installed)
cube agentic-ai machine-install cube-agentic-ai-esw

# Deploy it into the project with interactive service selection
cube agentic-ai project-add cube-agentic-ai-esw <project_top_folder> --interactive

# Install what the context needs (Python packages, tool bundles): project-add does not
cube agentic-ai doctor <project_top_folder> --bundles cube-agentic-ai-esw --fix

Omit --interactive to deploy the default and required services without prompting.

6. Add a context with explicit service selection

# Deploy only services S1 and S2 of a multi-service bundle
cube agentic-ai project-add cube-agentic-ai-esw <project_top_folder> --services S1,S2

# Install what these services need
cube agentic-ai doctor <project_top_folder> --bundles cube-agentic-ai-esw --fix

If the same context was already deployed with other services, this command adds S1,S2 to the existing selected set. It does not remove previously deployed services.

7. Update a deployed context to a newer version (upgrade)

Use explicit remove then re-add when you want a clean transition to a new context version and service set.

# Remove all deployed services for the context from the project
cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder>

# Install and deploy the selected version
cube agentic-ai project-add cube-agentic-ai-esw@<target-version> <project_top_folder> --services all

# Install what the new version needs. For ESW, its Python environment follows the project's choice.
cube agentic-ai doctor <project_top_folder> --bundles cube-agentic-ai-esw --fix

Use --services all for a project created with setup, which deploys every service. Otherwise pass the service IDs that project-lock-show lists. Add the --ide and --agentic-system options of the project when it does not use the default target. You can also use project-deploy --preset to apply a fully version-locked upgrade plan, followed by the same doctor --fix.

For eSW in a project that uses --python venv, the doctor --fix step creates the environment of the new version: see Python of the eSW context.

8. Roll back to an older context version (downgrade)

# Remove the current context deployment
cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder>

# Reinstall/reuse and deploy an older pinned version
cube agentic-ai project-add cube-agentic-ai-esw@<target-version> <project_top_folder> --services S1,S2

# Install what that version needs
cube agentic-ai doctor <project_top_folder> --bundles cube-agentic-ai-esw --fix

This explicit remove + add sequence avoids mixing artifacts from different deployed versions.

9. Two-step workflow: install first, deploy later

Useful when machine setup and project setup are done by different people or at different times.

# --- Machine setup (done once, by the operator) ---
cube agentic-ai machine-bootstrap

# --- Project setup (done per project) ---
# Deploy only from what is already installed. No downloads are attempted.
cube agentic-ai project-deploy-installed <project_top_folder> --mode interactive

# Install what the deployed contexts need. This step may download dependencies.
cube agentic-ai doctor <project_top_folder> --fix

10. Deploy to a specific IDE and agentic system

# Default: VS Code + GitHub Copilot
cube agentic-ai project-deploy <project_top_folder> --mode all

# No IDE binding, Claude Code as agentic AI system
cube agentic-ai project-deploy <project_top_folder> --mode all \
  --ide none --agentic-system claude-code

# Canonical layout only (no IDE-specific placement)
cube agentic-ai project-deploy <project_top_folder> --mode all --canonical

When you use --canonical, it takes priority over --ide and --agentic-system placement. In other words, deployment is written only to .cube-ai/ (portable layout), not to native IDE/agentic folders. If an agentic system later reshuffles those files, project-remove still targets the canonical paths recorded in the lock. Moved files require manual cleanup.

For a compact explanation of the two target dimensions and the common deployment patterns, see Target selection.

The tested pairings are VS Code + GitHub Copilot and no IDE binding + Claude Code. Other accepted target IDs are not tested. Run cube agentic-ai list-supported-targets to inspect the supported targets of your installer release. No target is production-validated.

11. Inspect what is installed and deployed

# What is installed on the machine?
cube agentic-ai machine-discovery

# Show only AI-relevant bundles (exclude OUT_OF_SCOPE)
cube agentic-ai machine-discovery --ai-only

# Same discovery but without generating machine-catalog.json
cube agentic-ai machine-discovery --no-json

# Generate machine catalog JSON at a custom path
cube agentic-ai machine-discovery --json-file ./artifacts/machine-catalog.json

# What is locked in a specific project?
cube agentic-ai project-lock-show <project_top_folder>

Notes:

  • machine-discovery always returns command-result JSON on stdout.

  • By default it also writes machine-catalog.json containing only the discovered bundle list array.

  • --ai-only filters out bundles classified as OUT_OF_SCOPE.

  • --json-file requires JSON file generation to be enabled. Combining --json-file with --no-json fails with INVALID_OPTION_COMBINATION.

12. Dry run before committing

# Preview what machine-bootstrap would install
cube agentic-ai machine-bootstrap --dry-run

# Preview what project-deploy would deploy (all mode — no prompts)
cube agentic-ai project-deploy <project_top_folder> --mode all --dry-run

# Preview with interactive selection (prompts shown, nothing deployed)
# Accepted bundles appear as SKIPPED_DRY_RUN in the result
cube agentic-ai project-deploy <project_top_folder> --mode interactive --dry-run

For machine-bootstrap --dry-run, entries that would change an already-installed bundle are reported as WOULD_UPDATE. Entries missing on the machine are reported as WOULD_INSTALL.

13. Remove a context from a project

# Remove all deployed services of a context (bundle entry removed from project)
cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder>

# Remove only specific services (other services remain deployed)
cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder> --services S3,S4

# Preview what would be removed before committing
cube agentic-ai project-remove cube-agentic-ai-esw <project_top_folder> --services S3 --dry-run

Use project-remove before reapplying a smaller service set if your intent is to replace rather than extend the current deployment.

Important for project-remove:

  • Removal decisions come from <project_top_folder>/.cube-ai/services-lock.json.

  • Services or files added manually outside installer deployment are not tracked and are not removed.

  • If deployment used --canonical and files were later reshuffled to non-canonical paths, project-remove still targets canonical-managed paths. Moved files may need manual cleanup.

  • The command does not perform lock-versus-manifest consistency verification before removing artifacts.

  • The command is project-scoped. It does not uninstall bundles from machine inventory.

  • After partial delete I/O failures, the services lock may be marked tainted (integrity.state = UNRELIABLE). In that state, run a dry-run first before any further mutating command.

Risk reduction recommendation:

  • For project-remove, run --dry-run first as a general safety step. Dry-run executes preflight checks (candidate/path validation) without changing project state.

14. Access the user manual

# Default output is TLDR quick reference on stdout
cube agentic-ai get-user-manual

# Explicit TLDR request
cube agentic-ai get-user-manual --format tldr

# Get the Markdown file paths so an AI agent can read the manual
cube agentic-ai get-user-manual --format markdown

# Open the HTML version in a browser (human use)
cube agentic-ai get-user-manual --format html