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.

Decision prompts (TypeSafe Jev)

Prompts for System-One decision models such as TypeSafe's Jev are question templates: typed questions (noul, choice, score) your code asks about a state it builds. They're emitted as get_decision(name), which returns an object with:

• batch() — ask(question_id, inputs, key=..., options=...) renders a question and returns a typed DecisionHandle (the key defaults to the question id; ask a question more than once under distinct keys). items() lists (key, question_id, question) to send. read(answers) validates each answer against its question (get(handle) → AnswerResult, get_or_throw(handle) → the answer model); read_all(answers) fails unless every answer is valid.
• question(question_id, inputs, options=...) and parse_answer(question_id, raw) — render or validate a single question.
• metadata — version and the recommended modelConfig, as for get_prompt.

triage = get_decision("@my-workspace/ticket-triage")
batch = triage.batch()
team = batch.ask("department", {"product": "Acme"})

res = httpx.post(
    "https://api.typesafe.ai/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}"},
    json={
        "model": triage.metadata["modelConfig"]["model"],
        "state": {"ticket": ticket},
        "questions": {key: question for key, _, question in batch.items()},
    },
).json()

batch.read(res["answers"]).get_or_throw(team).choice  # "billing" | "technical" | "sales"

The generated code has no provider request or response shape: you make the call (TypeSafe, OpenRouter's decisions endpoint, …) and add no runtime dependencies beyond chevron and pydantic. Guide: https://sufleur.com/docs/decision-models.

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

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

A tool contract is the model-facing definition of a tool — its wire name, the description that steers when it gets called, and the JSON Schema of its arguments — versioned like a prompt. A prompt version pins concrete tool versions, and sufleur generate turns those pins into typed bindings, provider-neutral definitions and a dispatch_tool that validates what the model sent. tool schema set checks a schema locally first, against the subset the generators can express, so nothing silently degrades to unknown/Any. As with prompts, publishing a tool version and changing its visibility are done in the web app.

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. For a decision prompt, pass --question <id> instead to print one rendered question (add --options '{...}' for an open choice).

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

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

• Sufleur platform — author and manage prompts: https://sufleur.com
• Source code, issues, release notes: https://github.com/sufleur/cli

License

MIT.