sufleur-cli

The CLI for Sufleur — the registry where you author, version, and publish LLM prompts. This is the consumer side: it installs prompts from your Sufleur workspace into your project the way pip installs packages — declared in sufleur.yaml, locked to sufleur-lock.yaml, generated into one Python module with full types and runtime helpers.

Create a workspace and start authoring prompts at https://sufleur.com.

What you call from your code

from generated.prompts import get_prompt

review = get_prompt("@my-workspace/code-review")

rendered = review.render("en", {"diff": "...", "language": "go"})
prompt: str = rendered["prompt"]  # ready-to-send prompt string

result = review.parse_output(llm_response_text)
if result["success"]:
    result["data"]  # Pydantic model, validated against the prompt's output schema
else:
    result["error"]

"@my-workspace/code-review" is checked at type-check time (mypy / pyright): typos fail, the entrypoint name "en" is narrowed against the prompt's available entrypoints (via @overload), and the input is a TypedDict derived from the JSON Schema declared on that entrypoint. The version that resolves at codegen time is pinned in sufleur-lock.yaml.

Install

pip install sufleur-cli
sufleur --help

Or with pipx for an isolated install:

pipx install sufleur-cli

The wrapper ships the prebuilt binary inside a per-platform wheel — pip selects the right one via PEP 425 platform tags. There's no Python interpreter in the invocation hot path; sufleur is the native binary on your PATH.

Quick start

mkdir my-app && cd my-app
sufleur init                                  # creates sufleur.yaml interactively
sufleur add @my-workspace/code-review ^1.0.0  # add + fetch + lock
sufleur generate                              # writes ./generated/prompts.py

The generated module imports two runtime peers. Install them with the [generated] extra:

pip install 'sufleur-cli[generated]'

…or add chevron (Mustache templating) and pydantic (output-schema validation, only needed when prompts have output schemas) directly to your project's dependencies. The CLI itself has no Python runtime deps; the [generated] extra exists so users who run init/add/install but never generate aren't forced to install code they don't use.

The generated code targets Python 3.10+ (PEP 604 union syntax).

What sufleur generate emits

A single .py module containing every prompt inlined (no runtime fetches). The public API is get_prompt(name), which returns a result object with:

  • render(entrypoint, input) → {"prompt": str} — Chevron renders the entrypoint template against input. The signature is narrowed via @overload per entrypoint, so type checkers reject the wrong input shape.
  • metadata — a TypedDict containing version, your workspace's custom metadata, and (when applicable) outputSchema.
  • parse_output(raw) (only present if the prompt has an output schema) — strips ``` fences, JSON-parses, and validates with a Pydantic model generated from the prompt's JSON Schema. Returns {"success": True, "data": <Model>} or `{"success": False, "error": str}`.

Plus generated TypedDicts per entrypoint, with field docstrings for any schema property that has a description:

class CodeReview_EnInput(TypedDict):
    diff: str
    """The unified diff to review."""
    language: str

Optional schema properties are wrapped in typing.NotRequired[...], and oneOf schemas become PEP 604 unions (X | Y).

Prompts published with DRAFT status emit a warnings.warn(...) when their get_prompt is called.

sufleur.yaml

The manifest. Looks like:

api_keys:
  my-workspace: ${MY_WORKSPACE_API_KEY}

prompts:
  '@my-workspace/greeting': '*'
  '@my-workspace/code-review': '^2.0.0'
  # alias: keep two pinned versions side-by-side under different names
  '@my-workspace/code-review-strict': '@my-workspace/code-review@~1.4.0'

output:
  language: python
  file: ./generated/prompts.py

api_keys is optional: public prompts install without any key (like public npm packages). A key is only needed for the private prompts of a workspace.

Constraints are npm-style semver ranges (^, ~, >=, exact, *). The resolution is recorded in sufleur-lock.yaml. Commit both files — sufleur.yaml is the source of truth, sufleur-lock.yaml is the receipt.

CI usage

sufleur install --frozen   # fail if lockfile is stale
sufleur generate

--frozen is the pip-compile-equivalent: refuses to update the lockfile, hard-errors if the manifest and lockfile disagree.

Commands

Command Description
sufleur init Interactive scaffolding for sufleur.yaml.
sufleur add @ws/name [range] Add a prompt, fetch it, update the lockfile. --alias <name> keeps multiple versions; --force overwrites an existing entry.
sufleur remove @ws/name Remove a prompt from the manifest and prune its cache (kept if another alias still resolves to the same version).
sufleur install Resolve the manifest, fetch what's missing, refresh the lockfile. --frozen for CI.
sufleur update [@ws/name] Re-resolve constraints — one prompt or all.
sufleur generate Regenerate the output file from the lockfile + cache.

-v / --verbose enables HTTP request/response logs on any command. Variables in .env are loaded automatically; per-workspace API keys can be referenced as ${ENV_VAR_NAME} in sufleur.yaml.

Authoring prompts from the CLI

The commands above install published prompts into your project. The CLI also exposes the full authoring side — designed so a coding agent (Claude Code, Cursor, etc.) can create, version, and edit prompts in your Sufleur workspace on your behalf.

Hand it to your agent

sufleur skill prints a markdown skill description — when to use the CLI, FQ-name format, the full command surface, JSON flags. Pipe it wherever your agent loads skills from:

# Claude Code (each skill is a directory with a SKILL.md inside)
mkdir -p ~/.claude/skills/sufleur && sufleur skill > ~/.claude/skills/sufleur/SKILL.md

# Cursor
sufleur skill > .cursor/rules/sufleur.md

The skill ships inside the binary, so it always matches the sufleur version on your PATH.

Log in

sufleur login    # device-code flow — opens a browser, polls until approved
sufleur me       # show the authenticated user
sufleur logout   # revoke the stored credential

Credentials land in $XDG_CONFIG_HOME/sufleur/credentials.yaml (or ~/.config/sufleur/credentials.yaml). This user credential is separate from the workspace API keys referenced in sufleur.yaml — those stay machine-to-machine, this one identifies you as the author.

Authoring commands

All accept --json. Prompts are addressed as @workspace/name, versions as @workspace/name@version (use the literal label draft while the version is unpublished).

Command What it does
workspace list List the workspaces you belong to, with your role
prompt create @ws/name --description "..." Create a new prompt in a workspace
prompt list @ws [--search ... --limit ... --offset ...] List prompts in a workspace
prompt get @ws/name Show one prompt's details
prompt update @ws/name --description "..." Update the description
version draft @ws/name Fork the latest published version into a new draft
version list @ws/name [--status DRAFT|PUBLISHED] List versions of a prompt
version get @ws/name@version Show one version's details
version delete @ws/name@draft Delete a draft (published versions are immutable)
version set-metadata @ws/name@draft --string K=V (or --from-file …) Patch or sync metadata
version delete-metadata @ws/name@draft --key K Remove a metadata key
version set-output-schema @ws/name@draft --file schema.json Replace the version's output schema
version set-model-config @ws/name@draft --provider anthropic --model NAME [--params '{...}'] Set the version's provider/model/parameters
version set-readme @ws/name@draft [--content STR | --file PATH] Replace the version's README
version get-readme @ws/name@version Print the version's README to stdout (raw markdown)
version dump @ws/name@version --to ./dir Export files, output schema, README, and metadata to disk
file list @ws/name@version List files in a version
file create @ws/name@draft --file path.mustache [--entrypoint] Add a new file
file update @ws/name@draft --name X [--file ...] [--rename Y] Replace content and/or rename
file delete @ws/name@draft --name X Delete a file
file set-entrypoint @ws/name@draft --name X [--clear] Mark (or unmark) a file as an entrypoint
eval get @ws/name@version [--file PATH] Print the version's eval YAML (skeleton if none)
eval validate @ws/name@version --file PATH Parse + type-check an eval YAML; saves nothing
eval push @ws/name@version --file PATH Validate, then save the eval
eval delete @ws/name@version Remove the eval from a version
eval run @ws/name@version [--watch] Enqueue a run; --watch streams to completion (CI gate)
eval runs @ws/name@version List recent runs, newest first
eval show <run-id> / eval watch <run-id> Summarise or follow a single run
eval cases <run-id> [--failed] Per-case pass/fail table for a succeeded run
eval case <run-id> <index> [--prompts] One case's inputs, output, assertions, and judges
dataset create @ws/name [--description ...] Create a dataset and its initial draft (private)
dataset list @ws / dataset get @ws/name List datasets, or show one with its versions
dataset update @ws/name --description "..." Edit the description
dataset dump @ws/name@version --to ./dir Export schema.json, cases.jsonl, and dataset.yaml to a directory
dataset cases push @ws/name@draft --file cases.jsonl Upload cases (JSONL/JSON/CSV); schema inferred on first upload
dataset cases pull @ws/name@version [--to cases.jsonl] Download a version's cases as JSONL
dataset schema get / set @ws/name@version [--file PATH] Read or refine a draft's JSON Schema
dataset version draft @ws/name New draft, carrying forward the latest published schema + cases
dataset version list @ws/name [--status DRAFT|PUBLISHED] List a dataset's versions
dataset version validate @ws/name@draft Check every case against the schema (non-zero exit on a violation)

An eval scores a prompt version against a dataset — judges, CEL assertions, and a passing threshold. Datasets are versioned collections of test cases, authored from the CLI too (the dataset … commands above) and referenced from the eval YAML via dataset.ref. Like prompts, publishing a dataset version and changing its visibility are done in the web app. Full guides: https://sufleur.com/docs/evals and https://sufleur.com/docs/datasets.

Render before publishing

sufleur prompt render <dir> --entrypoint <name> [--vars '{...}' | --vars-file path.json] runs the same Mustache pipeline as the generated runtime — useful for previewing a draft locally before publishing, or for quick experimentation against a version dump directory. No auth required.

Invocation modes

The sufleur command on your PATH is the Go binary itself. For tools that prefer module-style invocation:

python -m sufleur_cli --help

This goes through a tiny Python wrapper that locates the binary and os.execvps it (POSIX) or subprocess.runs it (Windows). Slightly slower because Python boots first, but useful when invoking the CLI programmatically from a Python tool that wants to be sure it's calling the binary in the active environment.

The find_sufleur_bin() helper is also importable:

from sufleur_cli import find_sufleur_bin
print(find_sufleur_bin())  # absolute path to the binary

Supported platforms

OS Architectures
macOS x86_64, arm64
Linux x86_64, aarch64 (manylinux 2.17 / glibc 2.17+)
Windows x86_64, arm64

Alpine / musl libc is currently unsupported (no musllinux wheel) — pip will refuse with "no matching distribution" rather than silently producing a broken install. There is no source distribution.

Links

License

MIT.

Project links

Data verified by PyPI on Jul 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for WTomas from gravatar.com WTomas

Credits

Author: Tamás Vajda

GitHub Statistics

Data verified by PyPI on Jul 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

generated

Tags

cli codegen llm prompts python sufleur

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

sufleur_cli-0.6.0-py3-none-win_arm64.whl (6.7 MB view details)

Uploaded Python 3Windows ARM64

sufleur_cli-0.6.0-py3-none-win_amd64.whl (7.3 MB view details)

Uploaded Python 3Windows x86-64

sufleur_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

sufleur_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

sufleur_cli-0.6.0-py3-none-macosx_11_0_x86_64.whl (7.1 MB view details)

Uploaded Python 3macOS 11.0+ x86-64

sufleur_cli-0.6.0-py3-none-macosx_11_0_arm64.whl (6.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file sufleur_cli-0.6.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: sufleur_cli-0.6.0-py3-none-win_arm64.whl
  • Upload date:
  • Size: 6.7 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 efab709b19213869d816b5d4ff77759fd09154c0b9467b1f2a8a9874329e6e87
MD5 fda5d39a19ad81d17eb05c5135ebc61c
BLAKE2b-256 28a1812f6140d2aad887c5f8705d834eae5e1ccbd95d0fa62b6080b9a6693119

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-win_arm64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sufleur_cli-0.6.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: sufleur_cli-0.6.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 7.3 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 c3920af64c523e1dd280710f2a053a01ac1a8bebba4ee64938fa05cd39ada375
MD5 3465f1165d2485d66f598d82f54ceab9
BLAKE2b-256 c6b73398f4e0f9599539c9058d3e470251bde79109eb25ffd4805ff5b0d05a7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-win_amd64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sufleur_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3c4ef6bdffcc9d0764be5262a605c8ed7391b6e8b19ed09af8aeb576549707ab
MD5 c5626cfc36c651d05bd74ff33bf5e1f2
BLAKE2b-256 5cb8881caa10835afb40d688e2ea0074ab339df85dc1d9a0b380855634482436

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sufleur_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3175ef11e75a6336bdc9f28f7944e4b3d368687fe50b4149b112257d0fb03919
MD5 6455469e90ffd3e4f1619e3efdc64053
BLAKE2b-256 c00264b4a94371718d37979ad812feb8e22b28b9459bef1dcc89e8901f8f1426

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sufleur_cli-0.6.0-py3-none-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 60e8d011ef0eaf47c67fe24fc7cb9944136dd6283d59b1599842a7661358ce6a
MD5 d05587ec2121b760e4ee5fe7672d448f
BLAKE2b-256 c526f2a1c260ec2d27cfbc9010b1090773677d4db6396b23005f5989168be719

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-macosx_11_0_x86_64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sufleur_cli-0.6.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for sufleur_cli-0.6.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7ef22a2be971f586368e6d3c5b3977ed47c937a1ed085ddb0d6b43ce11cfc5e6
MD5 783b1f5db369dd391d3a3797cfc6dd6f
BLAKE2b-256 e007497c069511b4abf693c19a964c5c0bb61a697d8b4c22b4cd201189dd6fca

See more details on using hashes here.

Provenance

The following attestation bundles were made for sufleur_cli-0.6.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on sufleur/cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.6.0 This release

6 files

0.5.0

6 files

0.4.0

6 files

0.3.0

6 files

0.2.1

6 files

0.2.0

6 files

0.1.0

6 files

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