CLI

tsg renders a TSG deployment description to Kubernetes manifests and can apply them. It needs Node.js 22 or newer and kubectl. It does not use Helm.

deployment.yaml
    ↓  validate → one complete in-memory deployment model
typed Kubernetes resources
    ↓  ordered patches, extra manifests, deletions
final deterministic manifests
    ├── commit to Git → Argo CD / Flux owns apply and prune
    └── tsg deploy → kubectl diff/apply/wait + inventory-backed prune

Rendering does not use a cluster, network connection, or kubeconfig. The same inputs and CLI version produce the same bytes. You can therefore review the rendered output in a merge request or produce it on an air-gapped runner.

Installation

npm install -g @tsg-dsp/cli@latest
tsg --version

tsg --version also prints every configuration apiVersion this CLI accepts, and which one it renders.

Commands

Command	What it does
tsg render <config> [-s <id>...] [-o <dir>]	Writes a manifest bundle without contacting a cluster or the network.
tsg diff <config> [-s <id>...]	Renders, then shows what applying it would change, including what would be pruned.
tsg apply <bundle-dir>	Applies an already-rendered bundle. Never reinterprets the configuration file.
tsg deploy <config> [-s <id>...]	render → diff → apply → wait → prune over a temporary bundle.
tsg uninstall <config> [-s <id>...] [--delete-data]	Deletes what the recorded inventory names. Data is retained unless --delete-data.
tsg status <config>	Lists the inventory sets recorded in the cluster.
tsg migrate <config> [-w]	Rewrites a configuration file at the newest apiVersion this CLI serves.
tsg secrets generate <config> [--apply]	Demo helper for the Secrets that rendered output only references.
tsg keys generate <stack> <client>	Writes a private_key_jwt key pair. Commit the public JWK, not the private JWK.

Only apply, deploy, diff, uninstall, status, and secrets generate --apply contact a cluster. render and migrate also skip the CLI release check, so they do not need network access.

Use --context <context> on any cluster-facing command to select a kubeconfig context. apply, deploy, and uninstall accept -y, --yes for non-interactive runs. apply and deploy also accept -t, --timeout for the per-resource readiness timeout. Run tsg <command> --help for the complete option list.

-s, --stack <id...> restricts a command to named stacks. A stack-selected run does not reconcile unselected stacks.

Typical use

# Review what would change
tsg diff participant.yaml

# Deploy
tsg deploy participant.yaml

# Inspect the CLI inventory
tsg status participant.yaml

For continuous deployment, commit the bundle instead of applying it:

tsg render participant.yaml -o gitops/tsg
git add gitops/tsg && git commit -m "chore: render TSG manifests"

Argo CD or Flux then owns apply and prune. Do not use tsg apply or tsg deploy on the same resources. The continuous deployment guide covers controller configuration and data retention.

The bundle

out/
  bundle.json                 # CLI metadata; never applied as a Kubernetes object
  manifests/
    infra/manifests.yaml
    stacks/
      authority/manifests.yaml
      alfa/manifests.yaml

bundle.json records the resolved image references, CLI version, and input apiVersion. Rendering with another CLI version may select different image tags. Set spec.images.<component>.digest for committed bundles.

A stack is the unit of deployment and Kubernetes ownership. Shared infrastructure renders into a separate infra set. It contains the Namespace and, in shared database mode, the CloudNativePG Cluster.

Ownership and pruning

Each apply set has an inventory ConfigMap in the cluster naming the exact identity of every object applied for it. Labels are used for status and selection; they are not deletion authority, because a label sweep would delete whatever happens to carry the label.

The CLI writes the inventory in two phases. Before changing the cluster, it records both the previous and desired objects. After apply and readiness succeed, it records only the desired objects and prunes the difference. If readiness fails after apply, the inventory still contains both sets. Fix the cause and rerun the command without a reset.

Prune and uninstall retain CloudNativePG Cluster, Database, and DatabaseRole resources plus PersistentVolumeClaims by default. --delete-data removes them in reverse apply order so the CLI drops each database before its owner role.

A full deployment also reconciles removed stacks and retains their data. A stack-selected deployment does not reconcile unselected stacks.

Prerequisites

Before applying anything, tsg deploy checks the prerequisites required by the rendered bundle. Required CRDs must exist and have a supported version. The CLI warns about an older controller version but does not block the deployment.

• CloudNativePG 1.30 or newer provides the DatabaseRole CRD used for component database logins.
• Gateway API 1.0 or newer is required when routing.gateway.enabled is set.
• An Ingress controller is required when routing.ingress.enabled is set. The CLI cannot detect whether a controller will serve the rendered Ingress.
• cert-manager is optional. Use it when you want automatic issuance of the TLS Secrets referenced by the routes.

TSG does not install or remove these cluster-level dependencies.

Related documentation

• Configuration reference documents every field and the versioning rules.
• Deployment guide covers deployment shapes, Secrets, Gateway API, and ongoing operations.
• Continuous deployment covers Flux and Argo CD.
• Getting started deploys a first participant.

Upgrading from the previous Helm-generating CLI? Use the manual migration guide. tsg migrate only handles versioned TsgDeployment documents.