Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command line

usage:
  cleat check  <file.cleat> [--vcs]
  cleat export <file.cleat> [options]
  cleat view   <file.cleat>  the exported resources in a browser, live
  cleat diff   <file.cleat>  what the output changes compared with a git revision
  cleat gen <schema>         print Cleat types for an OpenAPI document or CRD file
  cleat lsp                  language server on stdio (used by editors)
  cleat argocd generate      Argo CD plugin: export $ARGOCD_ENV_CLEAT_FILE (default main.cleat)
  cleat argocd params        Argo CD plugin: announce the file's inputs as parameters

options:
  --stdin                  read the source from stdin (the file name still places imports)
  --root <dir>             imports must stay inside this directory
                           (default: nearest directory with .git, else the file's directory)

export options:
  --input <file>           input values: a JSON or YAML object
  --set <name>=<value>     one input (decoded by its declared type); repeatable
  --argocd-params          read inputs from $ARGOCD_APP_PARAMETERS (Argo CD plugin)
  --target <t>             plain (default) | argocd (sync waves) | flux (needs --out)
  --json                   emit JSON instead of YAML
  --out <dir>              output directory (flux)
  --flux-source <name>     GitRepository name (flux; required)
  --flux-path <path>       repository path of --out (flux; default: .)
  --flux-namespace <ns>    namespace for Kustomizations (flux; default: flux-system)
  --flux-prefix <prefix>   prefix for Kustomization names (flux)

view options (also: --input, --set, --target plain|argocd):
  --port <n>               port on 127.0.0.1 (default: any free port)
  --no-open                don't open a browser
  --out <file.html>        write a self-contained snapshot instead of serving
  --diff <rev>             mark what changed compared with a git revision (branch, tag, commit)

diff options (also: --input, --set, --target plain|argocd):
  --base <rev>             the git revision to compare with (required)
  --exit-code              exit with status 1 when anything changed

cleat check

Parses and type-checks a file and the files it imports, and prints errors and warnings as file:line:col: error: message. It exits with status 1 if there are errors. --vcs also lists each refinement obligation and whether it was proved, refuted, or left to a runtime check.

cleat export

Checks the file, decodes the inputs, evaluates, and prints the exported documents as YAML (or JSON with --json). Nothing is evaluated if the file doesn’t check, and every bad input is reported before evaluation starts.

Inputs come from --input <file> (a JSON or YAML object), --set name=value (repeatable, and decoded by the input’s declared type: a string if the type accepts one, otherwise JSON), or Argo CD’s ARGOCD_APP_PARAMETERS (--argocd-params). When an input is given more than once, the last one on the command line wins.

cleat view

Shows the exported resources in your browser, laid out like a cluster dashboard: resources grouped by kind (Workloads, Network, Config, …), with kind-specific columns (replicas and images, Service ports and what they route to, Ingress routes, ConfigMap keys), a namespace filter and search, and the sync order of components. Selecting a resource shows its containers, labels, relations to other resources and its YAML.

The Map draws the resources as a graph, left to right in the order traffic and configuration flow: Ingresses, then Services (and autoscalers), then workloads, then the ConfigMaps, Secrets, volume claims and service accounts they use, with one box per namespace. References to resources that aren’t in the output appear as dashed nodes, so a broken link is visible where it is. Hovering a resource highlights what it’s connected to.

It also checks the resources against each other and against common mistakes, which the type checker can’t see. Warnings:

  • a Service that selects no workload, or targets a named port no selected container has;
  • an Ingress, HorizontalPodAutoscaler or PodDisruptionBudget pointing at something that isn’t there;
  • a workload whose selector doesn’t match its own pod labels (the API server rejects it);
  • an image with no tag or :latest, so what runs can change on its own;
  • a NetworkPolicy that blocks all incoming traffic to a workload a Service routes to;
  • the same resource defined twice (applying keeps only the last).

Notes, which may be fine: ConfigMaps, Secrets, volume claims and service accounts referenced but not in the output (they may already exist in the cluster), containers without resource requests or limits, and containers behind a Service without a readiness probe.

The page updates within a second when the file, or anything it imports, changes. Inputs start from --set and --input and can be edited on the page. The server listens on 127.0.0.1 only. With --out view.html it writes a self-contained snapshot instead, to attach to a pull request or a ticket.

Two options exist for editor integrations: --state prints the page’s data once as JSON (with --stdin for unsaved text), and cleat view --page prints the page itself, which they show and send that data to. Each resource’s data includes the line and column it’s defined at.

cleat diff

Compares the output with the same program at a git revision (a branch, tag or commit), with the same inputs:

$ cleat diff app.cleat --base main --set image=ghcr.io/acme/api:1.5.0
Comparing app.cleat with main (4dec382d89):
  ~ Deployment api
  + Service metrics
  - ConfigMap old-config
1 added, 1 changed, 1 removed (1 unchanged)

~ Deployment api
@@ -3,7 +3,7 @@
 metadata:
   name: api
 spec:
-  replicas: 1
+  replicas: 3
   selector:
     matchLabels:
       app: api

Resources are matched by kind, namespace and name. Every file the program reads at the revision comes from that revision, including imported modules; files git ignores (such as downloaded schemas) aren’t in any revision, so they’re read from the working tree. Inputs that only the working tree declares are left out for the revision. With --exit-code, it exits with status 1 when anything changed, for CI.

cleat view app.cleat --diff main shows the same comparison in the dashboard: new, changed and removed resources are marked in the tables and on the map, the overview lists them, “Changes only” hides the rest, and a changed resource’s details show its diff.

cleat gen

Prints the Cleat types generated from an OpenAPI document or a CRD file, which is what an import * as ns from "schema" sees.

Project root

Imports can’t leave the project root: the nearest directory above the entry file that contains .git, else the file’s own directory, or --root. Symbolic links are resolved before the check.