Choosing Commands

UNOFFICIAL/EXPERIMENTAL

Short Version

Here is what the command does. cub installer is an open-source plugin for the cub CLI. cub installer setup pulls a catalog package and writes its Kubernetes files locally, leaving delivery to kubectl, Argo CD or Flux. The generated scripts stop before doing any work when the plugin or kustomize is missing.

cub helm and cub installer are preparation tools. cub helm template previews an arbitrary chart and values. cub helm install records its source and rendered base in ConfigHub. cub installer reads a maintained catalog package with named configurations and recorded requirements.

The official ConfigHub tutorial teaches the product journey after configuration enters ConfigHub. New users do not need to compare the two plugins before following that tutorial.

A one-shot render is only operationally safe if its inputs are recorded. For a Helm chart, that means chart source, version, release name, namespace, values files, --set flags, capability assumptions, CRD choices, and generated facts. The catalog recipe path records those inputs today. A one-shot upload must keep its own source record if upgrades and reinstalls are expected to be repeatable.

What To Check Next

Each command path leaves the user at a different proof level. Check the matching surface before making a stronger claim.

If the first question is "can I use this chart?", start with the generated Chart Use Guide. It tells you whether the chart is a public catalog entry, a promotion-review candidate, a better-base-variant task, or a limitation-decision row. Then choose the command path below.

Graduation Path

A user can move through these paths over time. They do not need to choose the full catalog model on day one.

Existing apps enter through the same model without a recipe rewrite:

The important boundary is whether the user wants a one-time representation or a maintained artifact. Direct commands are good for one-time representation. Catalog entries are for repeatable bases, variant support, updates, patches, and proof.

For concrete "you should see something like this" checks after each command, use Expected Results And Clusters. It also explains when users need no cluster, a local kind cluster, their own Kubernetes cluster, or a temporary cluster created by cub cluster up.

Command Roles

cub helm template

Use this when you want a fast local Helm render through the cub-helm plugin.

It renders a chart to stdout or files. It can use values files and --set flags. It does not require a ConfigHub server connection.

Good for:

• inspecting chart output;
• debugging Helm values;
• creating a plain Helm baseline;
• checking CRD/resource split;
• producing input for a future import or analysis flow.

It does not create a maintained recipe, supported base variants, scan receipts, upload receipts, or a ConfigHub operating record.

Hook manifests are dropped by default. --include-hooks keeps them as ordinary resources but does not run Helm's hook lifecycle. CRDs are included unless --skip-crds is set. Charts that depend on live lookup results or non-default capabilities are outside this direct path.

cub helm install

Use this when you want to store an arbitrary Helm chart and its inputs in ConfigHub without first building a maintained catalog package.

The command creates two Spaces:

<component>-helm: one HelmSource Unit per release
<component>-base: rendered Kubernetes Units

The HelmSource Unit records the chart reference, values, and render options. The base is not assigned to a target. If --namespace is omitted, the chart is rendered with confighubplaceholder; a later cub variant create --namespace sets the deployment namespace.

This command does not apply anything to Kubernetes. Its hook, CRD, lookup, and capability limits are the same as cub helm template.

cub variant upload

Use this when you already have rendered Kubernetes files or a literal configuration OCI and want to create ConfigHub Units from them.

It does not render a Helm chart. It reads files, directories, stdin, or an oci:// manifest bundle. It records an OCI source reference and resolved digest when OCI is used.

Good for:

• quickly getting rendered configuration into ConfigHub;
• seeding a base Space from a reviewed OCI bundle;
• preserving file boundaries with --granularity per-file;
• starting from Helm, AICR, CI output, or hand-written Kubernetes files without building a catalog entry first.

It does not, by itself, create the maintained catalog proof: supported base variants, source/dependency locks, effective values, control-point reports, Helm-equivalence receipts, scan/gate receipts, live parity receipts, upgrade policy, or patch support.

cub installer

Use this when you want the maintained recipe/package path.

In helm-expt, a cub installer package is the catalog artifact. It has named base variants, rendered objects, receipts, checks, and a support story. Public users pull the package with its oci:// ref. Maintainers may use the local packages/... source path from a repo checkout when they are running proof scripts or editing the package.

Good for:

• using a curated public catalog entry;
• selecting a reviewed base such as default, existing-secret, server-only, no-crds, or http-clusterip;
• proving the rendered objects match regular Helm under recorded inputs;
• uploading reviewed objects into ConfigHub;
• publishing or handing off to OCI/GitOps;
• supporting future refreshes, patches, variants, and promotion.

Use cub installer setup to render a package. Use cub installer upload to load the rendered objects into ConfigHub.

cub variant create

Use this after a reviewed base has been uploaded to ConfigHub.

It clones an upstream Space and its Units into a downstream Space, preserves links to upstream Units, and applies variant metadata such as Variant, Environment, Region, and target.

Good for:

• creating environment, region, customer, or target variants;
• assigning a target;
• setting labels, annotations, gates, and policies;
• running PostClone triggers or approved post-render functions;
• preserving a visible relationship to the reviewed base.

It should not be used to hide a Helm rerender. If the request changes Helm render inputs, object count, object shape, or lifecycle behavior, route back to a cub installer base variant.

cub variant promote

Use this when a downstream Space was created by cub variant create and the reviewed upstream Space has changed. This is a normal ConfigHub server operation for components represented as upstream/downstream Spaces, not a helm-expt-only workflow.

Start with:

New to cub? Install the cub CLI first. Public catalog packages pull and render anonymously, and you sign in only once a command saves or changes ConfigHub data.

cub variant promote <downstream-space> --dry-run

Good for:

• seeing which downstream Units are behind their upstream Units;
• previewing mutation paths before writing;
• cloning Units that were added upstream after the downstream variant was created;
• associating the change with a ConfigHub changeset and change description.

It should not be treated as a Helm upgrade by another name. If the upstream change required a Helm rerender, that rerender belongs in the cub installer recipe/package path first. cub variant promote then carries the reviewed upstream changes into the downstream ConfigHub variant.

Existing Apps, Platforms, Stacks, And Live Clusters

Use this when the user asks:

Can I load from my existing app, apps, platform, stack, or live cluster?

The answer is yes, but it is an adoption path, not the same path as starting from a public catalog recipe.

Only graduate to a cub installer recipe when the app needs a maintained render path, future chart refreshes, and catalog-grade proof.

Routing Table

The Proposed Bridge

One possible future bridge is an import command:

cub installer import helm ...

or equivalent product wording.

This command does not exist. Such a bridge could turn a direct Helm chart, values file, or one-shot rendered upload into a maintained recipe/package candidate. Today, helm-expt uses repo generators and proof scripts to build the same artifact chain.

Repo Verifiers

The npm run ... commands are not product install commands. They verify the repo corpus and live-test evidence. Keep them out of the default user path unless the user is explicitly asking "how do I know this claim is true?"

Use them when you want to check claims:

For the full test-command map, use NPM Scripts.