Choosing Commands

UNOFFICIAL/EXPERIMENTAL

This guide explains which command path to use for a Helm chart. The commands answer different questions. They are complementary, not replacements for each other.

Short Version

cub helm and cub installer are preparation tools. cub helm imports an arbitrary chart and values. 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

helm template

Use this when you want a fast local Helm render.

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.

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. You can pull and render public catalog packages without an account. Commands that save or change ConfigHub data require you to sign in.

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

The proposed bridge is an import command:

cub installer import helm ...

or equivalent product wording.

That bridge should turn a direct Helm chart, values file, or one-shot rendered upload into a maintained recipe/package candidate. Until that exists as a product command, 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.