Zrb (Zaruba) is a Python-based tool that makes it easy to create, organize, and run automation tasks. Think of it as a command-line sidekick, ready to handle everything from simple scripts to complex, AI-powered workflows.

Whether you're running tasks from the terminal or a sleek web UI, Zrb streamlines your process with task dependencies, environment management, and even inter-task communication.

Documentation | Contribution Guidelines | Report an Issue

Zrb is designed to be powerful yet intuitive, offering a unique blend of features:

• 🤖 Built-in LLM Integration: Go beyond simple automation. Leverage Large Language Models to generate code, create diagrams, produce documentation, and more.
• 🐍 Pure Python: Write your tasks in Python. No complex DSLs or YAML configurations to learn.
• 🔗 Smart Task Chaining: Define dependencies between tasks to build sophisticated, ordered workflows.
• 💻 Dual-Mode Execution: Run tasks from the command line for speed or use the built-in web UI for a more visual experience.
• ⚙️ Flexible Configuration: Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or .env files.
• 🗣️ Cross-Communication (XCom): Allow tasks to safely exchange small pieces of data.
• 🌍 Open & Extensible: Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.

Let's create a two-step workflow that uses an LLM to analyze your code and generate a Mermaid diagram, then converts that diagram into a PNG image.

Before you start, make sure you have the following:

• An LLM API Key: Zrb needs an API key to talk to an AI model.

  export OPENAI_API_KEY="your-key-here"

  Zrb defaults to OpenAI, but you can easily configure it for other providers like Deepseek, Ollama, etc. See the LLM Integration Guide for details.

• Mermaid CLI: This tool converts Mermaid diagram scripts into images.

  npm install -g @mermaid-js/mermaid-cli

The easiest way to get Zrb is with pip.

pip install zrb
# Or for the latest pre-release version:
# pip install --pre zrb

Alternatively, you can use an installation script that handles all prerequisites:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/state-alchemists/zrb/main/install.sh)"

For other installation methods, including Docker 🐋 and Android 📱, check out the full Installation Guide.

Create a file named zrb_init.py in your project directory. Zrb automatically discovers this file.

💡 Pro Tip: You can place zrb_init.py in your home directory (~/zrb_init.py), and the tasks you define will be available globally across all your projects!

Add the following Python code to your zrb_init.py:

from zrb import cli, LLMTask, CmdTask, StrInput, Group
from zrb.builtin.llm.tool.code import analyze_repo
from zrb.builtin.llm.tool.file import write_to_file


# Create a group for Mermaid-related tasks
mermaid_group = cli.add_group(Group(
    name="mermaid",
    description="🧜 Mermaid diagram related tasks"
))

# Task 1: Generate a Mermaid script from your source code
make_mermaid_script = mermaid_group.add_task(
    LLMTask(
        name="make-script",
        description="Create a mermaid diagram from source code in the current directory",
        input=[
            StrInput(name="dir", default="./"),
            StrInput(name="diagram", default="state-diagram"),
        ],
        message=(
            "Read all necessary files in {ctx.input.dir}, "
            "make a {ctx.input.diagram} in mermaid format. "
            "Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`"
        ),
        tools=[
            analyze_repo, write_to_file
        ],
    )
)

# Task 2: Convert the Mermaid script into a PNG image
make_mermaid_image = mermaid_group.add_task(
    CmdTask(
        name="make-image",
        description="Create a PNG from a mermaid script",
        input=[
            StrInput(name="dir", default="./"),
            StrInput(name="diagram", default="state-diagram"),
        ],
        cmd="mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'",
        cwd="{ctx.input.dir}",
    )
)

# Set up the dependency: the image task runs after the script is created
make_mermaid_script >> make_mermaid_image

Now, navigate to any project with source code. For example:

git clone git@github.com:jjinux/gotetris.git
cd gotetris

Run your new task to generate the diagram:

zrb mermaid make-image --diagram "state-diagram" --dir ./

You can also run it interactively and let Zrb prompt you for inputs:

zrb mermaid make-image

Zrb will ask for the directory and diagram name—just press Enter to accept the defaults.

In moments, you'll have a beautiful state diagram of your code!

Prefer a graphical interface? Zrb has you covered. Start the web server:

zrb server start

Then open your browser to http://localhost:21213 to see your tasks in a clean, user-friendly interface.

Zrb brings AI capabilities right to your command line.

Start a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.

zrb llm chat

For a single question, use the ask command for a fast response.

zrb llm ask "What is the capital of Indonesia?"

• Dive Deeper: Explore the Full Zrb Documentation

• Watch the Video Demo:

  

• Bugs & Feature Requests: Found a bug or have a great idea? Open an issue. Please include your Zrb version (zrb version) and steps to reproduce the issue.

• Contributions: We love pull requests! See our contribution guidelines to get started.

• Support Zrb: If you find Zrb valuable, please consider showing your support.

  

Did you know? Zrb is named after Zaruba, a powerful, sentient Madou Ring that acts as a guide and support tool in the Garo universe.

Madou Ring Zaruba (魔導輪ザルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor. (Garo Wiki | Fandom)