hull plan

Synopsis

hull plan renders a package directory and compares it against the current stored state — the Terraform plan for hull. It shows what applying that directory would add, change, or destroy, and (by default) where each change comes from: the source template file, and the origin of every changed value.

It also writes a portable, apply-able plan artifact (rendered manifest + parameters + content hash) that hull apply can execute later, unchanged.

When to use it

Before an upgrade, to review exactly what will change and why.
In change-management flows: CI produces the JSON artifact, a human reviews the diff, a deploy stage runs hull apply --plan.

What happens when you run it

Renders [package-path] (default .) against the merged values (--profile + -f + --set*).
Derives the release identity from the package’s hull.yaml name (unless -r/--release is given) and reads its latest stored state.
Diffs the render against that state — every field shown, so an edited label is never hidden — and annotates each change with its provenance.
Optionally writes the apply-able JSON artifact (--out, or --format json).

No resources are applied. The cluster is read only to fetch the stored state, and that is best-effort: with no reachable cluster or no prior state, every resource is reported as a create.

Usage

hull plan [package-path] [flags]

The release name is not a positional argument — it comes from hull.yaml.

Flags

Flag	Type	Default	Description
`-r, --release`	string	(from hull.yaml)	state to compare against; overrides the derived name
`--profile`	string	—	profile to apply
`-f, --values`	stringArray	—	values file (repeatable)
`--set`	stringArray	—	key=value (repeatable)
`--set-string`	stringArray	—	key=value forced as string (repeatable)
`--action`	string	“install”	action the artifact represents: install or upgrade
`-o, --out`	string	”-“	write the JSON plan artifact to this file
`--format`	string	“text”	stdout format: `text` (change preview) or `json` (artifact)
`--no-color`	—	—	disable colored diff output

Persistent flags inherited from `hull`

Flag	Type	Description
`--debug`	—	enable debug output
`--kube-context`	string	Kubernetes context to use
`--kubeconfig`	string	path to kubeconfig file
`-n, --namespace`	string	Kubernetes namespace

Examples

Plan the package in the current directory against its state:

cd ./mychart
hull plan

Output (in → out):

hull plan: update  mychart / apps  (package .)

~ update  Deployment/mychart-api
      from: deployment.yaml
      ~ spec.replicas
          - 1   (state)
          + 3   ← set (replicas=3)
      ~ spec.template.spec.containers.0.image
          - "registry/api:1.4.0"   (state)
          + "registry/api:1.5.0"   ← values-file (prod.yaml)

Plan: 0 to add, 1 to change, 0 to destroy.

Read the origins: spec.replicas changed because of --set replicas=3; the image changed because prod.yaml set it. from: names the template to open.

Compare against a differently-named state:

hull plan -r prod-web .

Produce the apply-able artifact and apply it later:

hull plan --out plan.json
hull apply --plan plan.json

Emit the artifact to stdout for a pipeline:

hull plan --format json > plan.json