CLI reference#

helm-schema generates a schema from one positional argument (the chart) plus flags. The generated schema goes to standard output unless --output is given; diagnostics go to standard error. The subcommands hand an already generated schema to Helm: shorten writes a copy with short $defs keys, and lint and template run Helm on a shortened copy of the chart.

helm-schema [OPTIONS] <CHART_DIR>
helm-schema shorten [--map <PATH>] [--compact] <INPUT> <OUTPUT>
helm-schema lint [--helm <PATH>] <CHART> [HELM_ARGS]...
helm-schema template [--helm <PATH>] <CHART> [HELM_ARGS]...

Run helm-schema --help for the authoritative, version-specific summary.

Argument#

Argument	Description
`<CHART_DIR>`	Chart directory or packaged chart archive (`.tgz`/`.tar.gz`) to analyze. Required.

Output#

Flag	Description
`-o`, `--output <FILE>`	Write the schema to a file; standard output is used when absent.
`--output-layout <LAYOUT>`	`auto` (default): pretty JSON until Helm’s 5 MiB limit requires compact JSON with short names. `pretty`: always pretty with readable names. `compact`: always compact with short names. Every mode writes oversized output with a warning, never a size error.
`--compact`	Deprecated: compact JSON whitespace only. Retains readable names unless `--shorten-defs` is also used. Conflicts with explicit `--output-layout`.
`--strip-descriptions`	Remove JSON Schema `description` annotations. Schema-aware: a property literally named `description` is kept.
`--profile <full\|lean>`	Select emitted validation detail. `full` is the default. `lean` retains mandatory and local ordinary facts, while dropping root ordinary conditionals, terminals, and kind partitions.
`--root-anchored-conditionals <on\|off>`	Override root-anchored ordinary conditional emission.
`--local-conditionals <on\|off>`	Override locally anchored ordinary conditional emission.
`--terminal-clauses <on\|off>`	Override unconditional and guarded terminal emission.
`--kind-partitions <on\|off>`	Override kind-partition refinements. At least one applicable anchor lane must remain enabled when this is on.
`--keep-refs`	Leave file/URL `$ref` strings as-is. By default external refs are resolved into root-level `$defs` so the output is self-contained. Conflicts with `--inline-refs`.
`--inline-refs`	Fully inline resolved file/URL `$ref`s instead of writing `$defs`.
`--no-minimize`	Keep repeated subtrees inline instead of interning them into root-level `$defs`. Interning is on by default.
`--defs-names <source\|destination>`	Name the `$defs` entries helm-schema creates by the schema path their content comes from (`source`, the default) or by their first reference (`destination`).
`--shorten-defs`	Deprecated: short definition names only; pretty JSON unless `--compact` is also used. Conflicts with explicit `--output-layout`.
`--defs-map <PATH>`	Write the map from each short key to its readable name; an empty object when the chosen layout keeps names unchanged.

`shorten`#

helm-schema shorten <INPUT> <OUTPUT> renames the $defs entries of a generated schema to short keys, the form to hand Helm when the readable schema exceeds Helm’s 5 MiB chart-file limit. --map <PATH> writes the map from each short key to its readable name; --compact writes compact JSON. This subcommand and all generation layouts warn when the written schema is over the limit and still exit successfully. Default generation automatically compacts and shortens oversized pretty output and reports the resulting size on stderr.

`lint` and `template`#

helm-schema lint <CHART> [HELM_ARGS]... and helm-schema template <CHART> [HELM_ARGS]... run helm lint or helm template on a copy of the chart directory whose root values.schema.json is shortened and compact, so a reviewed readable schema over Helm’s limit still works. The copy lives in a fresh directory under TMPDIR (or the platform’s temporary directory) and is removed when Helm ends, also when SIGINT, SIGTERM or SIGQUIT stops Helm on Unix, however slowly its output is read (on Windows only a console Ctrl-C is caught, and other console events such as closing the window may end helm-schema before the copy is removed; a failed removal is reported on standard error without changing the exit status); links in the chart are copied as the files and directories they point to, and a link to a directory that contains it is refused. Dependency schemas and archives are copied unchanged, and Helm still applies .helmignore. A chart without a root values.schema.json runs unchanged, without a copy.

Everything after the chart is passed to Helm verbatim, including --help; one -- right after the chart is dropped. Helm keeps the current directory, so relative -f and --set-file paths mean what they mean for Helm. Helm’s standard output and error are relayed line by line; in diagnostics (both streams of lint, standard error of template) each complete #/$defs/<short key> reference token is replaced by the readable name, while the manifests template writes to standard output stay byte for byte; the command exits with Helm’s status (on Unix, a signal that ended Helm ends helm-schema too). template puts the chart first, so name the release with --name-template rather than Helm’s positional NAME CHART form.

Flag	Description
`--helm <PATH>`	The Helm executable. Defaults to `$HELM`, then `helm` on `PATH`.

Short keys are looked up in the root schema’s map only; a dependency schema whose own $defs use the same short spelling is translated as if it were the root’s.

See Output for what these produce.

Configuration#

Flag	Description
`--config <PATH>`	Read policy from this file instead of discovering the root chart’s `helm-schema.yaml`. Relative paths use the invocation working directory.
`--no-config`	Ignore discovered chart policy configuration. Conflicts with `--config`.
`--print-effective-config`	Print resolved policy values and per-field sources without analyzing the chart.

See Configuration for the file format, retention contract, and precedence rules.

Kubernetes schemas#

Flag	Description
`--k8s-version <VERSION>`	Kubernetes minor version dir(s) to consult, in priority order; first is primary. Repeatable. Default: `v1.35.0`.
`--k8s-version-fallback <auto\|N>`	Auto-extend a single `--k8s-version` with older minors. `auto` uses the default window; `<N>` sets the window size. Conflicts with `--strict-k8s-version`.
`--strict-k8s-version`	Suppress the auto-fallback chain.
`--k8s-schema-mirror <URL>`	Additional upstream Kubernetes schema mirror. Repeatable. Available in strict and loose modes.
`--k8s-schema-cache-dir <DIR>`	Managed cache root for Kubernetes schemas. Subject to the cache invalidation contract.
`--no-cache`	Bypass cache reads and re-check upstream directly. Successful responses and authoritative 404s still refresh the cache.
`--offline`	Force offline; use only local caches. Equivalent to `HELM_SCHEMA_ALLOW_NET=0`.
`--no-k8s-schemas`	Skip upstream Kubernetes schemas entirely (template analysis only).

See Kubernetes schemas.

CRD schemas#

Flag	Description
`--crd-version-lookup <strict\|loose>`	CRD version lookup mode. Default `strict` (only the exact `(group, kind, version)`); `loose` adds a local cross-scan and informational hints. Never substitutes a version.
`--strict-crd-version`	Short alias for `--crd-version-lookup=strict`.
`--crd-catalog-mirror <URL>`	Additional upstream CRD catalog mirror. Repeatable. Available in both modes.
`--crd-catalog-cache-dir <DIR>`	Managed cache root for CRD schemas. Subject to the cache invalidation contract.
`--crd-override-dir <DIR>`	Hand-maintained schema overrides at the top of the lookup chain. Never wiped; not a managed cache. Keyed by `(group, version, kind)`.
`--crd-cache-record-source`	Write a `<schema>.json.meta` sidecar next to each CRD cache entry recording the fetch URL and timestamp.

See CRD schemas.

apiVersion inference#

Flag	Description
`--api-version-guess`	Enable bounded apiVersion inference for kinds whose `apiVersion` the analyzer couldn’t pin. Conflicts with `--strict-api-versions`.
`--strict-api-versions`	Disable apiVersion inference entirely.

See apiVersion inference.

Chart traversal#

Flag	Description
`--exclude-tests`	Skip `templates/tests/**`.
`--no-subchart-values`	Omit vendored subchart defaults under `charts/` from the composed values.
`-f`, `--values <FILE>`	Additional values files whose comments layer into schema descriptions. Documentation metadata only — no type hints or accepted paths. Repeatable.
`--infer-required`	Mark unconditionally-guarded paths as `required` on their parent. Paths with a `default <expr>` fallback are excluded.
`--open-root`	Omit the generated `additionalProperties: false` at the chart values root, so unknown top-level keys pass. Nested structural and Kubernetes closures stay. An authoring assertion, recorded in `x-helm-schema-policy.authoring`.
`--declared-types <assert\|annotate>`	`assert` (default): a declared default asserts its type where no other evidence governs the path. `annotate`: declared defaults document names and values only; template and Kubernetes constraints remain.

Overrides#

Flag	Description
`--override-schema <FILE>`	Schema files merged on top of the inferred output, in the order given. Repeatable.

See Schema overrides.

Diagnostics#

Flag	Description
`--diag-format <text\|json>`	Format for diagnostics on stderr. Default `text`. `json` emits one structured object per line.

See Diagnostics.

Environment variables#

Variable	Effect
`HELM_SCHEMA_ALLOW_NET=0`	Disable all network access (same as `--offline`).
`HELM_SCHEMA_K8S_SCHEMA_CACHE`	Kubernetes schema cache root (same as `--k8s-schema-cache-dir`).
`HELM_SCHEMA_CRD_SCHEMA_CACHE`	CRD catalog cache root (same as `--crd-catalog-cache-dir`).

Mutually exclusive flags#

--keep-refs and --inline-refs
--strict-k8s-version and --k8s-version-fallback
--api-version-guess and --strict-api-versions
--k8s-version-fallback is also rejected alongside multiple explicit --k8s-version values.

Development tracing#

Perfetto tracing is available in the unpublished helm-schema-dev binary. It runs the same commands and arguments as helm-schema, with an additional --trace-output <FILE> option. Build it from the workspace with cargo build --release -p helm-schema-dev.