ChecklistFabrik: Simple Process Management

ChecklistFabrik ("clf") helps to standardise processes and to-do lists in teams and organisations and to answer questions such as "What needs to be done next?" or "Where am I in the process?". All you need is a YAML file that defines the workflow as a checklist, Python to run ChecklistFabrik, and a browser to display the interactive HTML checklist generated by clf.

ChecklistFabrik can be run with uv without a permanent install via uvx checklistfabrik, or installed as a tool with uv tool install checklistfabrik. Other installation methods (pipx, pip, development setup) are documented on the PyPI page. ChecklistFabrik was developed in the Linuxfabrik, is open source, and is licensed under the UNLICENSE.

Details and documentation can be found at linuxfabrik.github.io/checklistfabrik.

What for

ChecklistFabrik is not just for the software industry or IT operations. It fits every area where checklists and standardised workflows are used, from server maintenance and deployments to shift handovers in manufacturing, pre-flight checks or onboarding procedures.

Typical use cases:

• Standard Operating Procedures (SOPs): recurring procedures in IT ops, manufacturing, laboratories, medicine, service or administration that should always go the same way.
• Deployments and commissioning: reproducible step-by-step procedures that leave a documented record at the end.
• Maintenance and recurring routines: monthly server maintenance and patch days in IT, inspections and handovers in manufacturing.
• Onboarding and training: walking new staff through a standardised procedure.
• Audits and compliance: traceable reports that show who completed which steps and when.

What ChecklistFabrik can do

• Dashboard: running clf-play without arguments opens a web dashboard listing every template and report in the current directory. Start a new checklist or continue an existing one with a single click.
• Auto-save: progress is written to the report on every page change. Closed the browser tab by mistake? Just re-open the report and pick up where you left off.
• Conditional pages and tasks (when): pages or individual tasks only appear when a condition is met (for example only on Linux targets, only when a specific value has been entered).
• Sub-checklists and template includes: split long procedures into reusable building blocks. A checklist can embed other checklists as a "Run" card.
• Jinja templating: variables, conditionals, dynamically generated text, with Markdown supported in questions and answers.
• Git-friendly: templates and reports are plain YAML files. Diff-friendly, reviewable in pull requests, easy to archive.

Terms

• Template: a YAML file that defines a workflow as a checklist. Designed for reuse, not for direct execution.
• Page: a page of the checklist that displays multiple tasks at once.
• Task: a single step (checkbox, text input, radio button, Markdown block, etc.).
• Report: the result of a checklist run, a YAML file generated from the template that records the progress.

Step 1: Create a checklist as a YAML template

Checklists are defined with YAML. Features such as Jinja templating and various controls allow ChecklistFabrik to create complex and dynamic processes. Markdown is supported for designing elements such as questions and answers. Checklists can be modular and imported from other checklists. With when expressions, pages or tasks only appear under certain conditions. In the example below the Linux-specific instruction only shows up if "Linux" was previously selected as the target platform.

Example (extract):

title: 'Deploy Red Hat Build of Keycloak'
version: '1'
report_path: '$HOME/deploy-keycloak-{{ now().strftime("%Y%m%d") }}.yml'
pages:

  - title: 'Questionnaire'
    tasks:
      - linuxfabrik.clf.checkbox_input:
          label: 'Target Platform?'
          values:
            - value: 'Linux'
            - value: 'Windows'
          fact_name: 'platform'

  - title: 'Before you start'
    tasks:
      - linuxfabrik.clf.checkbox_input:
          values:
            - label: 'Make sure you have [OpenJDK 17](https://openjdk.java.net/) installed'
          required: true

  - title: 'Start Red Hat Build of Keycloak'
    tasks:
      - linuxfabrik.clf.checkbox_input:
          values:
            - label: 'On Linux: `bin/kc.sh start-dev`'
        when:
          - '"linux" in (platform | map("lower"))'

Step 2: Running the checklist

The Python tool clf-play interprets the YAML file, renders it into interactive HTML, starts a local Python web server and displays the checklist in the browser.

clf-play --template examples/deploy-keycloak.yml

Step 3: Save the checklist

Progress through the checklist can be saved at any time. Saving the templates and results ("reports") in Git repositories allows team collaboration, easy monitoring of process progress, a rollback function, and an audit trail.

We can help

Want to learn more about ChecklistFabrik or see a demo? Get in touch.