CKL Tools Reference

The ckl command-line tool validates recipes, checks safety rules, and generates the interactive site. These are the tools you use to work with CKL notation.

Validating Recipes

check — Verify correctness and safety

The most important command. It verifies that a recipe is syntactically correct, all ingredients and equipment are declared, and all safety rules are satisfied.

ckl check recipes/
ckl check recipes/pasta.ckl.md

Use --strict to treat warnings as errors (useful in CI):

ckl check recipes/ --strict

Use --json for machine-readable output:

ckl check recipes/ --json

lint — Check best practices

Runs best-practice rules separately. These are warnings, not errors — things like searing without pre-heating or deglazing a cold pan.

ckl lint recipes/
ckl lint recipes/ --strict

Building

build — Full validation

Runs all validation phases (syntax, safety, best practices) and produces build artifacts.

ckl build recipes/
ckl build recipes/chicken.ckl.md

docs — Generate the interactive site

Generates HTML documentation in the site/ directory. This is the command that produces the interactive cooking pages with step-by-step instructions, timers, and cross-references.

ckl docs

Inspection

ast — View recipe structure

Outputs the parsed recipe structure as JSON. Useful for understanding how CKL interprets a recipe or for building tools on top of CKL.

ckl ast recipes/pasta.ckl.md

format — Format CKL files

Formats CKL source files to consistent style.

ckl format recipes/

Exit Codes

0 — Success. The recipe is valid.
1 — Error. Syntax error, safety violation, or file not found.

JSON Output

Use --json with any command for machine-readable output:

ckl check recipes/ --json

Output format:

[
  {
    "file": "recipes/example.ckl.md",
    "diagnostics": [
      {
        "message": "Error message",
        "severity": "error",
        "line": 10,
        "column": 1,
        "code": "E001"
      }
    ]
  }
]

CLI Reference