CLI reference

Hull’s command-line interface is rooted at hull. Every command has a --help output reachable via hull <cmd> --help; this directory holds the long-form reference for each, with description, every flag, and examples.

Global flags

These apply to every command and can also be set as defaults via environment variables.

Flag	Env	Description
`-n, --namespace <ns>`	`HULL_NAMESPACE`	Kubernetes namespace for the operation.
`--kubeconfig <path>`	`KUBECONFIG`	Path to kubeconfig file.
`--kube-context <name>`	—	Active kubeconfig context.
`--debug`	`HULL_DEBUG`	Enable debug logging.
`--allow-plaintext-auth`	`HULL_ALLOW_PLAINTEXT_AUTH`	Send registry credentials over plaintext HTTP.
`--oci-plain-http`	`HULL_OCI_PLAIN_HTTP`	Use plain HTTP for OCI registries instead of HTTPS.
`--oci-insecure-skip-tls-verify`	`HULL_OCI_INSECURE_SKIP_TLS`	Skip TLS verification for OCI registries.

Environment variables

Variable	Purpose
`HULL_CONFIG_HOME`	Config dir (default: `~/.config/hull`).
`HULL_CACHE_HOME`	Cache dir (default: `~/.cache/hull`).
`HULL_DATA_HOME`	Data dir (default: `~/.local/share/hull`).
`HULL_DEBUG`	Enable debug logging when truthy.
`HULL_OCI_PLAIN_HTTP`	Use HTTP for OCI instead of HTTPS.
`HULL_OCI_INSECURE_SKIP_TLS`	Skip TLS verification for OCI.
`HULL_ALLOW_PLAINTEXT_AUTH`	Allow sending registry credentials over plaintext HTTP.
`HULL_DRIVER`	Release storage driver (`secret`, `configmap`, `memory`, `sql`). Default `secret`.
`HULL_DRIVER_SQL_DSN`	SQL DSN when driver is `sql`.
`HULL_NAMESPACE` (or `HELM_NAMESPACE`)	Default namespace; legacy aliases recognised.
`KUBECONFIG`	Standard Kubernetes kubeconfig path.

Exit codes

Code	Meaning
`0`	Success.
`1000-1999`	Input validation (CLI args, manifest format).
`2000-2999`	Business logic (release not found, version conflict).
`3000-3999`	Resource (cluster resource missing or unavailable).
`4000-4999`	Permission (RBAC, auth).
`5000-5999`	System (timeout, dependency failure, internal error).

Hull prints both the textual error and the numeric code to stderr; scripts can branch on the code.

Commands by category

Release lifecycle

Command	One-liner
`install`	Install a hull package as a new release.
`upgrade`	Upgrade an existing release to a new revision.
`rollback`	Roll back a release to a previous revision.
`uninstall`	Uninstall a release.
`status`	Show a release’s current status and revision.
`list`	List releases.
`history`	Show release history.
`get`	Get release details (manifest, values, hooks, notes).
`audit`	Show the chronological audit trail for a release.
`prune`	Drop superseded revisions, keeping the most recent N.
`rename`	Rename a release in-place (preserve history).
`releases`	Manage cross-release dependencies declared in `hull-releases.yaml`.

Diff, plan, drift

Command	One-liner
`diff`	Show what would change on upgrade.
`plan`	Render and persist an apply-able plan.
`apply`	Execute a previously-saved plan.
`drift`	Detect drift between the stored manifest and live cluster state.
`reconcile`	Re-apply the stored manifest to converge cluster state.
`canary`	Staged upgrade through replica percentages with bake periods.
`multi-install`	Install a release into multiple clusters.

Authoring

Command	One-liner
`create`	Scaffold a new package.
`init`	Scaffold from a built-in template.
`lint`	Validate a package for correctness.
`template`	Render templates locally.
`debug`	Debug template rendering.
`dev`	Watch a package and re-render on changes.
`config`	Interactively build a values file from `values.schema.json`.
`values`	Show effective values, optionally with per-key resolution trace.
`scan`	Find common values across packages; extract a base layer.
`policy`	Evaluate package policies against rendered manifests.
`graph`	Render a dependency graph of a release.
`metrics`	Sample CPU/memory; recommend requests/limits.

Packaging

Command	One-liner
`package`	Package as a `.hull.tgz` archive.
`publish`	Publish a package to a registry.
`sbom`	Emit a CycloneDX 1.5 SBOM for a release.
`adopt`	Claim existing in-cluster resources as a hull-managed release.
`dependency`	Manage layers and required packages.

Repositories and OCI

Command	One-liner
`repo`	Manage hull package repositories.
`registry`	Manage OCI registries.
`login`	Store credentials for a package registry.
`logout`	Remove stored credentials.
`pull`	Download a package from a repository or OCI.
`registry push`	Push a package archive to an OCI registry.
`search`	Search for packages.
`show`	Show package metadata, values, README, etc.

Signing

Command	One-liner
`keyring`	Manage the PGP keyring used for provenance verification.
`package verify`	Verify a `.prov` signature against the local keyring.

Workspaces

Command	One-liner
`workspace`	Orchestrate multiple packages declared in `hull-workspace.yaml`.

Plugins and marketplace

Command	One-liner
`plugin`	Manage hull plugins.
`marketplace`	Browse and install signed plugins.

Test

Command	One-liner
`test`	Run tests for a release.

Operations

Command	One-liner
`controller`	Reconcile HullRelease CRs declared in the cluster.
`purge`	Clean up everything hull has installed.

Compat and migration

Command	One-liner
`helm-compat`	Helm chart compatibility helpers.
`migrate`	Convert a Helm chart to a hull package.

Misc

Command	One-liner
`version`	Print the hull version.
`env`	Print hull’s environment information.
`completion`	Generate shell completion scripts.