Skip to main content

levain-cli

The open toolchain for authoring Levain agent recipes: a validator, model checker, and code generator for the recipe formats that Levain agents are defined in.

A recipe package is one of two kinds, set by kind under [tool.levain] in its pyproject.toml:

  • graph (the default): a graph.tla PlusCal spec (the agent's node graph and state) plus a Python package with one function per node.
  • harness: one engine session (Claude Code or Hermes) declared in [tool.levain.harness]: engine, model, effort, system prompt, tools, MCP servers and state fields, plus for Claude Code the skills, instructions and settings it ships to the workspace. No graph and no Python.

This tool checks both and keeps a graph's two halves coherent:

  • validate — parse a spec, enforce the recipe grammar profile, check graph topology, translate PlusCal to TLA+, and model-check the result with TLC (deadlock and termination).
  • validate-package — validate a package of either kind. For a graph: all of the above, plus Python source cross-checks (every @node function exists and is importable) and pyproject.toml checks. For a harness: the [tool.levain.harness] keys and values, the prompt file, the shipped skills, instructions and settings, the state fields and the MCP server names.
  • generate-state — regenerate _state.py, the typed GraphState TypedDict a graph's node functions program against. A harness has no state module.

Install

uv tool install levain-cli

TLC model checking (stages 4-5) needs a Java runtime; tla2tools.jar is fetched automatically on first use. Without Java the tool degrades to the pure-Python stages and says so — the Levain platform re-runs full validation on every push, so nothing is lost, only local feedback latency.

Use

levain validate graph.tla
levain validate-package .
levain generate-state .
levain --version

The import package is levain_recipe — use it to lint recipes from your own CI or scripts:

from levain_recipe.validate import validate_fast, validate_recipe

validate_recipe(dir) reads the package's kind and returns a ValidatedSpec for a graph or a HarnessSpec for a harness, or a list of errors.

Validation errors are prescriptive ([stage] line N: message, with TLC counterexample traces) — they are the recipe format's primary teaching interface, for humans and agents alike.

For MCP clients that cannot run shell commands (e.g. Claude Desktop), levain mcp serves the same operations over stdio; install with the [mcp] extra.

What this is not

Recipe execution — compiling a validated spec into a running agent, sandboxing, integrations — happens on the Levain platform. Passing local validation is necessary, not sufficient: the platform validates again server-side before a version can be published.

Metadata

Release files for levain-cli 0.1.28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for levain-cli 0.1.28
File Size Uploaded Provenance Actions
levain_cli-0.1.28.tar.gz 55.8 kB With provenance Details for levain_cli-0.1.28.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for levain-cli 0.1.28
File Interpreter ABI Platform Actions
levain_cli-0.1.28-py3-none-any.whl Python 3 none any Details for levain_cli-0.1.28-py3-none-any.whl

Total release size: 121.7 kB

Release files / levain_cli-0.1.28.tar.gz

Download URL levain_cli-0.1.28.tar.gz
Size 55.8 kB
Tags Source
SHA-256 checksum
How to use checksums
db14d4ce713f61fc1811aed15a4750f6b37ab0a9cca332dde669487229af95cf
BLAKE2b-256 checksum
How to use checksums
812d9c48ca2bac1004f26d4c61cb6b89d95118985e1fe0f04f6c262de8650a7b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / levain_cli-0.1.28-py3-none-any.whl

Download URL levain_cli-0.1.28-py3-none-any.whl
Size 65.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a31d46e5bc5ec47c160793cead7351e8a89c702abe1c5ebf5f92cef07a7bff4b
BLAKE2b-256 checksum
How to use checksums
1711eb282a717d5dc66607820447934e36fdd2e6b4e8199233f1091a77b6925b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for levain-cli 0.1.28

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for levain_cli-0.1.28.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page