Platform CLI

The bsqai-platform CLI is the primary tool for generating and deploying BullSequana AI platform manifests. It reads TOML configuration and Jinja2 templates, produces Kubernetes manifests, seals or externalizes secrets, and pushes the output to a Git repository for ArgoCD to reconcile.

Prerequisites

Install and run the CLI

From the repository root, install an editable command that keeps using that checkout's templates and configuration:

uv sync
uv tool install --editable . --python 3.12
bsqai <command> [arguments] [options]

Keep the repository clone after installation. You can also run commands without installing the entry point:

uv run -m src.cli.main <command> [arguments] [options]

Commands

test-k8s

Test connection to the Kubernetes cluster using the kubeconfig at <repo-root>/.kube/config.

uv run -m src.cli.main test-k8s

Exits with code 0 on success, 1 on failure. Use this to verify cluster connectivity before running any deployment commands.

list-components

List all components available in the current platform version.

uv run -m src.cli.main list-components

Components are discovered by scanning directories under src/manifests/source/<group>/. The output is sorted alphabetically.

validate

Validate the structure of all component definitions.

uv run -m src.cli.main validate

For each component, validation checks:

• variables.toml exists
• the format field is one of helm, kustomize, or yaml
• required files are present (values.yaml.j2 for Helm, kustomization.yaml for Kustomize)

load

Load and resolve all TOML variables for the specified component(s). Useful for inspecting resolved configuration without generating manifests.

uv run -m src.cli.main load                    # all components
uv run -m src.cli.main load keycloak             # specific component

Resolution applies environment variable overrides, generators, and global defaults. See Configuration model for the full resolution chain.

apply

Generate output manifests for the specified component(s).

uv run -m src.cli.main apply all -r             # all components, replace existing output
uv run -m src.cli.main apply keycloak             # specific component only

This is the core command. For each component it:

1. Loads and resolves the global platform.toml and all component variables.toml files
2. Renders Jinja2 templates (values.yaml.j2, resources/*.yaml.j2, secrets/*.yaml.j2)
3. Seals any rendered Secret manifests with kubeseal, or replaces them with ExternalSecret resources when SECRETS_BACKEND=external-vault
4. Generates an ArgoCD Application manifest for each component
5. Generates parent app-of-apps manifests for each non-empty group (common, coreai, inference, proai)

Output is written to src/manifests/output/.

push-manifests

Commit and push the generated manifests to the Git repository.

bsqai push-manifests "Release 1.4.0"

Requires three environment variables:

The CLI clones the target repository, replaces its content with the generated output from src/manifests/output/, commits, and pushes.

apply-sealing-key

Install the sealed-secrets keypair and registry pull secret on the Kubernetes cluster.

uv run -m src.cli.main apply-sealing-key                  # default namespace: sealed-secrets
uv run -m src.cli.main apply-sealing-key my-namespace      # custom namespace

This command touches the cluster directly. It applies:

• the sealed-secrets TLS keypair from src/manifests/seal/
• the container registry pull secret assembled from the primary registry settings and optional COMMON_DOCKER_CONFIG_JSON

Run this once before the first deployment to bootstrap the sealing infrastructure. Do not run it as a routine upgrade step: existing clusters must retain their current sealing identity.

The command refuses to run when SECRETS_BACKEND=external-vault, because there is no sealing key to install.

apply-registry-secret

Create or update the container registry pull secret in a namespace.

bsqai apply-registry-secret                      # default namespace: default
bsqai apply-registry-secret external-secrets     # External Secrets Operator namespace

The command touches the cluster directly. It creates the namespace when it does not exist. The secret is named after COMMON_REGISTRY_SECRET (default registry-secret) and is built from the primary registry settings and optional COMMON_DOCKER_CONFIG_JSON.

Use it for a namespace that pulls images from the private registry before any GitOps-managed secret exists there. With SECRETS_BACKEND=external-vault, run it for external-secrets before the first sync.

list-vault-secrets

Print the Vault entries that the rendered ExternalSecret resources read.

bsqai apply all -r
bsqai list-vault-secrets

The output has one line per remote key, as <key>: <property>, .... A * means the whole entry is copied into the secret. The command reads src/manifests/output/ and fails when it finds no ExternalSecret, so render with SECRETS_BACKEND=external-vault first.

See External Vault secrets.

helm-apply

Deploy a bootstrap component directly through Helm, outside the generated GitOps hierarchy.

uv run -m src.cli.main helm-apply argocd
uv run -m src.cli.main helm-apply gpu-operator

Use argocd for the Argo CD control plane on a fresh deployment. Use gpu-operator only on a GPU cluster that needs the platform-supplied NVIDIA Kubernetes integrations; it installs the platform chart values for node feature discovery, the device plugin, GPU feature discovery, DCGM metrics, and MIG support. The supplied values expect the node driver and container runtime to exist already.

The command:

1. Logs into the container registry
2. Loads and renders the component's values.yaml.j2
3. Runs helm install or helm upgrade against the cluster

Requires COMMON_REGISTRY_NAME, COMMON_REGISTRY_AUTH_USERNAME, and COMMON_REGISTRY_AUTH_TOKEN environment variables.

upgrade record-baseline

Reproduce the original installation from its supported release source and private deployment inputs, compare it with the original GitOps commit and live state, and write a new local managed-baseline receipt:

uv run -m src.cli.main upgrade record-baseline \
  --source-checkout /secure/checkouts/platform-1.3.0 \
  --manifest-checkout /secure/checkouts/original-deployment-manifests \
  --output /secure/upgrade/baseline-1.3.0.json

Source and manifest checkouts must be clean and pinned to the original supported commits. The source checkout needs the original configuration, generated secrets and sealing material. Add --gpu only if the original installation includes the platform GPU Operator. Recording does not accept arbitrary current state as a baseline or overwrite an existing receipt. See the managed upgrade prerequisites.

upgrade plan

The 1.3.0-to-1.4.0 managed path requires an unchanged, independently verified installation baseline. Validate it without changing Git or Kubernetes:

export BASELINE=/secure/upgrade/baseline-1.3.0.json
uv run -m src.cli.main upgrade plan --from 1.3.0 --to 1.4.0 --baseline "$BASELINE"

The plan checks original provenance, Application inventory and content, chart/bootstrap configuration, health, idle operations and existing upgrade state. A version label or matching chart versions alone is insufficient. Changed or unverifiable deployments require the manual procedure.

--offline prints the migration contract only. Do not combine it with --baseline or --accept-risk; it cannot establish live eligibility.

upgrade apply

Render, validate, publish and execute the resumable upgrade from the target checkout:

# Read-only live validation; local render output can change.
uv run -m src.cli.main upgrade apply --from 1.3.0 --to 1.4.0 --baseline "$BASELINE" --dry-run

# Publish the immutable snapshot and execute the cutover.
uv run -m src.cli.main upgrade apply --from 1.3.0 --to 1.4.0 --baseline "$BASELINE"

The checkout's VERSION must equal --to. Keep GIT_BRANCH on the current 1.3.0 manifests branch; the managed CLI creates a separate upgrade/<domain>/<version>-<timestamp> ref. All generated Git sources use that immutable ref.

The live dry run imports known live credentials, compares Secret data and public routes, checks release-specific prerequisites and reuses unchanged SealedSecret ciphertext. It can update ignored local render output and generated_secrets.env, but does not push Git or mutate Kubernetes. Review missing active credential sources before applying; generated replacements are not evidence of continuity.

The command rejects unsupported version pairs, a checkout-version mismatch, conflicting upgrade state and reuse of an existing remote ref for new publication. --offline requires --dry-run and cannot be combined with live-baseline options. The historical 1.2.1-to-1.3.0 procedure has its own baseline and options; do not mix the two procedures.

Run apply in a persistent session and follow the agent-assisted monitoring and resume guidance. Do not run competing syncs or discard recovery artifacts while an upgrade is active.

upgrade status

Read the durable checkpoint in the argocd/bsqai-platform-upgrade ConfigMap:

uv run -m src.cli.main upgrade status

The output includes the version pair, phase, immutable manifest ref/revision, completed Application count, update time and last error. The checkpoint contains no credentials. Private recovery material is separate, under artifacts/upgrades/<cluster-uid>/<run-id>/ in the target checkout; preserve it and the same inputs for resume.

Debugging

Both push-manifests and helm-apply work in temporary locations — a cloned copy of the manifests repository and a rendered Helm values file respectively — that are deleted when the command finishes.

Set CLEANUP_TEMPORARY_FILES=false (platform 1.2.1 and later) to keep them after the run for inspection. Any other value, or leaving the variable unset, keeps the default cleanup behavior.

Typical deployment sequence

Initial deployment

This sequence uses the default Sealed Secrets backend.

# 1. Verify cluster connectivity
bsqai test-k8s

# 2. Generate all manifests
bsqai validate
bsqai apply all -r

# 3. Push to the manifests repository
bsqai push-manifests "Initial deployment"

# 4. Install the sealing key
bsqai apply-sealing-key

# 5. Bootstrap ArgoCD
bsqai helm-apply argocd

# 6. Optional: install the NVIDIA Kubernetes integrations on a GPU cluster
bsqai helm-apply gpu-operator

With SECRETS_BACKEND=external-vault, replace step 4 with bsqai apply-registry-secret external-secrets and the Vault token secret. See External Vault secrets.

After Argo CD starts, it reconciles the manifests from Git and deploys all enabled components to the cluster. The GPU Operator command is not required for CPU-only deployments or when the cluster owner already provides an equivalent supported NVIDIA integration.

Subsequent configuration changes

# 1. Regenerate all manifests (replace mode wipes the output directory to avoid stale configuration)
bsqai apply all -r

# 2. Push to the manifests repository
bsqai push-manifests "Description of changes"

ArgoCD detects the Git changes and reconciles automatically.

Upgrade from 1.3.0

Follow the managed or manual upgrade procedure. For an unchanged managed installation, use the baseline receipt, live plan and dry run before apply. A configuration render or fresh-install bootstrap does not perform this migration.

For older deployments, use the separate 1.2.1-to-1.3.0 guide first.

Image inventory and package SBOMs

Use Inventory and SBOM handoff to generate the configured image/chart inventory, resolve digests, and verify release package reports. Inventory generation is a separate Python script, not a bsqai images command.

Related pages

• Configuration model
• GitOps workflow
• Component anatomy
• Deployment sequence