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.27

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.27
File Size Uploaded Provenance Actions
levain_cli-0.1.27.tar.gz 55.8 kB With provenance Details for levain_cli-0.1.27.tar.gz

Built distribution (wheel)

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

Total release size: 121.7 kB

Release files / levain_cli-0.1.27.tar.gz

Download URL levain_cli-0.1.27.tar.gz
Size 55.8 kB
Tags Source
SHA-256 checksum
How to use checksums
8cdaf9599a32c0d7bbe2f56cfdaa6d2c98a98abc4a29c5b85f2e94f7d635453a
BLAKE2b-256 checksum
How to use checksums
693223c6f81bd362223c78e626756d592b93fcbcdbb0ee8f5ca1ada0f11bf00d
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 13, 2026.

Transparency log

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

Download URL levain_cli-0.1.27-py3-none-any.whl
Size 65.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
045065d31c2102c690ffc42fcf244d305a9f6bbe5f17b0ad9794db164c68164c
BLAKE2b-256 checksum
How to use checksums
2479feb09f2e8402b4e0415ba1902c8313714c02fd5561ab1972705b43c323cf
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 13, 2026.

Transparency log

Security for levain-cli 0.1.27

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.27.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 13, 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