llm-workflow-engine: a terminal-first CLI and workflow manager for LLMs

What llm-workflow-engine solves, and for whom

Most people meet an LLM through a browser tab. That works until the prompt stops being a one-off and becomes a step in something repeatable: summarise a directory of PDFs, classify rows in a spreadsheet, chain a model call behind a shell command. At that point you are either writing glue code around an HTTP client or pasting between windows.

LWE takes the second path and formalises it. The README describes the project as a "Power CLI and Workflow manager for LLMs", and the two halves are distinct. The CLI half is an interactive terminal session: you type a prompt, the model answers, and the conversation persists. The workflow half runs Ansible playbooks, so an LLM call becomes a task alongside file copies, template rendering and shell commands.

The audience follows from that split. It suits engineers who already treat the terminal as their working environment and who think in playbooks. It does not suit someone who wants a chat product with a sidebar of conversations, and it does not suit a team that needs a versioned, documented Python SDK to import into an application. The README lists a Python API as a highlight, but the packaging metadata exposes exactly one console entry point, lwe, and no library-level API contract.

One lineage note matters when you search for older material: the README states that LWE grew out of the original ChatGPT Wrapper project by mmabrouk, and CHATGPT_WRAPPER.md in the repository root documents the transition. Tutorials written for the old name will not map cleanly onto current commands.

How LWE is put together: backends, plugins and Ansible

The repository layout tells you more about the architecture than the README does. There is a top-level lwe/ package, and inside it a backends/ tree with an api/ subtree containing schema/alembic, workflow/*.cfg and workflow/*.yaml. Alembic is a database migration tool, so the API backend owns a real schema and migrates it; the dependencies list sqlalchemy and alembic together, and docker-compose.yml mounts a ./tmp directory alongside the source tree, which is where a container-local SQLite file would live.

Plugins are the extension mechanism. pyproject.toml declares an entry point group named lwe_plugins, empty in the core package, and the README links to a documentation page about core plugins. That is the standard Python packaging pattern: an out-of-tree package registers itself under lwe_plugins and LWE discovers it at runtime. Provider support for anything other than OpenAI arrives this way, which is why the README can claim support for Cohere and Huggingface without listing those clients as dependencies.

Workflows are Ansible. The README says you "easily integrate calls to an LLM into larger workflows via Ansible Playbooks", and ansible>=8.0 plus ansible-core>=2.15 sit at the top of the dependency list. This is the most consequential design decision in the project. You get Ansible's inventory, variables, conditionals and error handling for free, and you inherit Ansible's learning curve and its execution model. A workflow is not a Python function graph; it is a playbook run.

The remaining dependencies hint at the intended use cases: beautifulsoup4 and pdfminer.six and pymupdf4llm for extracting text from documents, openpyxl for spreadsheets, tiktoken for token accounting, rich and prompt-toolkit for the terminal interface, pyperclip for clipboard access. Document ingestion is a first-class concern here, not an afterthought.

Installing llm-workflow-engine and running a first prompt

The README points to a documentation page for installation rather than inlining the steps, so the commands below come from the packaging files in the repository. The package requires Python 3.10 or newer, per requires-python in pyproject.toml. A pip install from the source tree gives you the lwe console script, and the editable form is what the Dockerfile itself uses.

python -m venv .venv
source .venv/bin/activate
pip install -e .

After that, lwe is on your PATH. The project also ships a Dockerfile and a docker-compose.yml. The compose file builds from the repository, names the container lwe-container, mounts the source tree at /src and ./tmp at /tmp, and passes OPENAI_API_KEY through from your environment. The Dockerfile installs sqlite3 for the default database and then runs pip install -e . on the copied source.

export OPENAI_API_KEY=sk-...
docker compose up

Configuration is YAML. The repository root contains config.sample.yaml, which is the file to copy and edit before a first real session; the README links to a configuration page in the documentation for the full key list. Expect to set at minimum the provider and the model you want to talk to.

cp config.sample.yaml config.yaml
lwe

Running lwe opens the interactive shell. The README describes the experience as calling and interacting with ChatGPT or GPT-4 from the terminal, with pyperclip available for clipboard moves and rich rendering the output. Conversation state goes into the local database managed by the API backend, so sessions survive a restart. For a workflow, the documentation's workflows page is the entry point; the playbooks you write are ordinary Ansible files, and the repository keeps its own under lwe/backends/api/workflow/ with .cfg and .yaml files alongside the schema.

Where LWE gets in your way

The Ansible dependency is the sharpest edge. Ansible 8 pulls in a large collection of modules, and the install footprint is correspondingly large for what is, in the simplest case, a chat client. If your workflow is three sequential API calls, you are paying for a configuration management system to express them. The README does not offer a lighter path.

The Python API is the weakest promise in the README. It is listed as a highlight, but pyproject.toml declares no library entry points beyond the lwe script and the lwe_plugins group, and the packaging does not advertise a stable importable surface. Treat the Python API as an internal detail that may change between releases rather than something to build a product on.

The Docker image is labelled experimental in the README, and the compose file reinforces that: the restart policy is commented out, and the container mounts your source tree, which is a development arrangement rather than a deployment one. The docker-entrypoint.sh script is referenced but its contents are not described in the README.

Provider coverage is uneven by construction. OpenAI is the supported path, with the README describing direct calls to the ChatGPT endpoint for whatever models your account can reach. Everything else arrives through plugins, and the core package ships none. Tool use is likewise conditional: the README says it works "for supported providers", without naming them.

Finally, the project's own documentation is the only reliable source for upgrade behaviour. The README links to an upgrading page, which implies migrations are handled, but nothing in the repository files explains what happens to an existing database when a new version changes the schema. Alembic is present, so migrations exist; their operator-facing story is not spelled out in the files at hand.

The realistic alternative: writing the calls yourself

The honest comparison is not another workflow engine. It is the langchain stack that LWE already depends on. Note the version drift between the two dependency files: requirements.txt pins langchain>=0.3.19,<0.4, while pyproject.toml requires langchain>=1.2.16,<2. That is a major-version gap between the repository's own two manifests, and it tells you the project is mid-migration on its LLM abstraction layer.

If you go directly to langchain, you get a Python library with a documented API, and you write the orchestration in Python: functions, loops, error handling, tests. You give up Ansible's inventory and templating, and you give up the terminal shell and the local conversation database. You also take on more code, because nothing is doing the plumbing for you.

LWE's bet is that Ansible is a better orchestration language for LLM pipelines than Python is. That bet pays off when the surrounding work is already Ansible, when the operators running the job are not Python developers, and when you want the model call to sit next to a file copy in the same readable task list. It loses when the pipeline needs branching logic that reads naturally in code, when you want unit tests around the prompt assembly, or when the team has never written a playbook. Those are not small conditions.

Maintenance, licence and upgrade cost

The repository is not archived. Its last push was on 2026-09-05, and the same day saw the v0.22.25 release. The two releases before that landed on 2026-07-15 and 2026-04-30, so the cadence is roughly monthly to quarterly rather than continuous. Version numbers are in the 0.22.x range, which by convention signals that the maintainers have not declared a stable interface.

The dependency list is where upgrade cost actually accumulates. Ansible, four langchain packages, sqlalchemy, alembic and tiktoken all move independently, and the langchain constraint in pyproject.toml is already a major version ahead of the one in requirements.txt. A user installing from source and a user installing from the requirements file are not getting the same stack. Watch that divergence before you pin anything.

Licence is MIT, declared both in pyproject.toml and in the repository's License file, and the README repeats it. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and permission notice travel with it. That is the extent of what the repository states. Anything about your own obligations when you ship a modified LWE belongs with your legal counsel, not with this article.

One practical cost that is easy to overlook: the project depends on a fork of textract pinned to a specific commit in requirements.txt (textract @ git+https://github.com/thehunmonkgroup/textract@61a25dcb6f1d3e747b6e58b716d058f3dfe3d662). A git-pinned dependency is only as available as the repository hosting it, and it will not resolve from a package index alone.

Editorial conclusion

Adopt llm-workflow-engine if your team already automates with Ansible and wants model calls as one more step in a playbook, or if you want a terminal chat client that keeps history in a local SQLite database. Do not adopt it if you need a supported Python library API, a web interface, or a tool that works without an OpenAI-compatible endpoint. Before committing, verify three things against the current documentation: that your provider is covered by a plugin, that the Ansible version you run satisfies the ansible>=8.0 floor, and that you are willing to track a project whose releases arrive in irregular bursts (v0.22.23 in April 2026, v0.22.24 in July, v0.22.25 in September).

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. llm-workflow-engine/llm-workflow-engine on GitHub
4. README
5. Releases