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. |
--compact | Compact JSON instead of the default pretty-printed output. |
--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 $refs 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 | Rename every $defs entry to a short key, for a schema handed to Helm directly. Never applied automatically. |
--defs-map <PATH> | With --shorten-defs, write the map from each short key to its readable name. |
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. Both commands warn when the written schema is still over the limit.
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 & tracing#
| Flag | Description |
|---|---|
--diag-format <text|json> | Format for diagnostics on stderr. Default text. json emits one structured object per line. |
--trace-output <FILE> | Write a Perfetto-readable trace of the run. |
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-refsand--inline-refs--strict-k8s-versionand--k8s-version-fallback--api-version-guessand--strict-api-versions--k8s-version-fallbackis also rejected alongside multiple explicit--k8s-versionvalues.