zrb 2.9.2

Your Automation Powerhouse

🤖 Zrb: Your Automation Powerhouse

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.

Contribution Guidelines | Report an Issue

---

📑 Table of Contents

• 🔥 Why Choose Zrb?
• 🚀 Quickstart Part 1: Your First Basic Pipeline
• 🚀 Quickstart Part 2: AI-Powered Workflow
• 🖥️ Try the Web UI
• 💬 Interact with an LLM Directly
• ⚙️ Installation & Configuration
• 🤝 CI/CD Integration
• 🗺️ Documentation Directory
• 🎥 Demo Video
• 💖 Support Zrb
• 🎉 Fun Fact

---

🔥 Why Choose Zrb?

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.

---

🚀 Quickstart Part 1: Your First Basic Pipeline in < 2 Minutes

Let's start with the absolute basics: defining simple units of work and chaining them together. You only need Python installed.

1. Define Your Tasks

Create a file named zrb_init.py in your project directory (or your home directory for global access!).

# zrb_init.py
from zrb import cli, CmdTask, Task

# 1. Define tasks.
# CmdTask is perfect for running shell commands.
prepare_env = CmdTask(
    name="prepare-env", 
    cmd="echo 'Environment prepared!'"
)

# Task is for pure Python logic.
build_app = Task(
    name="build-app",
    action=lambda ctx: ctx.print("Building application in pure Python...")
)

deploy_app = CmdTask(
    name="deploy-app", 
    cmd="echo 'Deploying app to the cloud ☁️'"
)

# 2. Register tasks to the main 'cli' object so Zrb knows about them
cli.add_task(prepare_env, build_app, deploy_app)

# 3. Define the execution order (The Directed Acyclic Graph - DAG)
# prepare-env runs first, then build-app, then deploy-app
prepare_env >> build_app >> deploy_app

2. Run Your First Pipeline!

Now, open your terminal and run:

zrb deploy-app

Zrb will see that deploy-app depends on build-app, which depends on prepare-env. It will automatically run them in the correct sequential order:

[prepare-env] Environment prepared!
[build-app] Building application in pure Python...
[build-app] Build complete.
[deploy-app] Deploying app to the cloud ☁️

Congratulations! You've just built and run your first Zrb automation pipeline.

---

🚀 Quickstart Part 2: Your First AI-Powered Workflow in < 5 Minutes

Now that you understand the basics, let's unleash Zrb's full power. This example uses an LLM to analyze your code and generate a Mermaid diagram, then converts that diagram into a PNG image.

1. Prerequisites

• An LLM API Key: Zrb needs an API key to talk to an AI model (OpenAI is default, but others are supported).

  export OPENAI_API_KEY="your-key-here"
  

• Mermaid CLI: This tool converts Mermaid diagram scripts into images. Install it via npm:

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

2. Update Your zrb_init.py

Add the following to your existing zrb_init.py file (or create a new one if you prefer to keep examples separate):

# zrb_init.py (continued)
from zrb import cli, LLMTask, CmdTask, StrInput, Group
from zrb.llm.tool.code import analyze_code
from zrb.llm.tool.file import write_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 using an LLM
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_code, write_file],
    )
)

# Task 2: Convert the Mermaid script into a PNG image using CmdTask
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

3. Run Your AI-Powered Workflow!

Navigate to any project with source code (e.g., a Python project). For instance, if you've cloned a repository:

git clone https://github.com/someuser/my-python-project.git
cd my-python-project

Now, run your new task:

zrb mermaid make-image

Zrb will interactively ask for the directory and diagram name. Just press Enter to accept the defaults (./ and state-diagram). The AI will analyze your code, generate the Mermaid script, and mmdc will convert it to a PNG. In moments, you'll have a beautiful diagram of your code!

---

🖥️ Try the Web UI

Prefer a graphical interface? Zrb has you covered. Explore the full details in the Web UI Guide.

zrb server start

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

---

💬 Interact with an LLM Directly

Zrb brings AI capabilities right to your command line. For full details on configuring and using the AI assistant, see the LLM Integration Guide.

Interactive Chat

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

zrb llm chat

---

⚙️ Installation & Configuration

Ready to dive deeper into getting Zrb set up and customized? Our comprehensive guides cover everything you need:

• Installation Guide: Details on pip install, the automated install.sh script, Docker images, and even running Zrb on Android (Termux/Proot).
• Environment Variables & Overrides: An exhaustive list of all general environment variables to customize Zrb's behavior.
• LLM & Rate Limiter Configuration: Everything you need to configure your LLM provider, manage token budgets, and fine-tune AI behavior.

---

🤝 CI/CD Integration

Integrate Zrb into your Continuous Integration/Continuous Deployment pipelines for robust, automated workflows. See the CI/CD Integration Guide for examples with GitHub Actions, GitLab CI, and Bitbucket Pipelines.

---

🗺️ Documentation Directory

Zrb scales from simple scripts to massive automation ecosystems. Explore the documentation to unlock its full potential:

I. Core Concepts

The foundational pillars of the framework.

• Tasks & Execution Lifecycle
• CLI and Groups
• Inputs
• Environments (Envs)
• Session, Context & XCom

II. Task Types & Built-ins

Pre-packaged operations you can use immediately.

• Task & CmdTask
• Readiness: HttpCheck & TcpCheck
• Automation: Triggers & Schedulers
• File Ops: Scaffolder & RsyncTask
• Built-in Helper Tasks (Git, Base64, UUID, HTTP, etc.)

III. Advanced Features

Taking your automation to the next level.

• LLM Assistant (Pollux) & AI Tasks
• LSP Support (Language Server Protocol)
• Hook System (Claude Code Compatible)
• White-labeling: Create a Custom CLI
• CI/CD Integration

IV. Configuration

• Environment Variables & Overrides
• LLM & Rate Limiter Configuration

V. Guides & Specifications

• Web UI Guide
• Upgrading Guide (v0.x to v1.x)
• Maintainer Guide
• Changelog
• Claude Code Compatibility
• Technical Spec: LLM Journal System

---

🎥 Demo Video

Watch a video demonstration of Zrb in action:

---

💖 Support Zrb

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

---

🎉 Fun Fact

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)