# π€ 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.
[Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [Contribution Guidelines](https://github.com/state-alchemists/zrb/pulls) | [Report an Issue](https://github.com/state-alchemists/zrb/issues)
---
## π₯ 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.
---
## π Quick Start: Your First AI-Powered Workflow in 5 Minutes
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.
### 1. Prerequisites: Get Your Tools Ready
Before you start, make sure you have the following:
- **An LLM API Key:** Zrb needs an API key to talk to an AI model.
```bash
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](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/configuration/llm-integration.md) for details.
- **Mermaid CLI:** This tool converts Mermaid diagram scripts into images.
```bash
npm install -g @mermaid-js/mermaid-cli
```
### 2. Install Zrb
The easiest way to get Zrb is with `pip`.
```bash
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
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](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/README.md).
### 3. Define Your Tasks
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`:
```python
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
```
### 4. Run Your Workflow!
Now, navigate to any project with source code. For example:
```bash
git clone git@github.com:jjinux/gotetris.git
cd gotetris
```
Run your new task to generate the diagram:
```bash
zrb mermaid make-image --diagram "state-diagram" --dir ./
```
You can also run it interactively and let Zrb prompt you for inputs:
```bash
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!
---
## π₯οΈ Try the Web UI
Prefer a graphical interface? Zrb has you covered. Start the web server:
```bash
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.
### Interactive Chat
Start a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.
```bash
zrb llm chat
```
### Quick Questions
For a single question, use the `ask` command for a fast response.
```bash
zrb llm ask "What is the capital of Indonesia?"
```
---
## π₯ Demo & Documentation
- **Dive Deeper:** [**Explore the Full Zrb Documentation**](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)
- **Watch the Video Demo:**
[](https://www.youtube.com/watch?v=W7dgk96l__o)
---
## π€ Join the Community & Support the Project
- **Bugs & Feature Requests:** Found a bug or have a great idea? [Open an issue](https://github.com/state-alchemists/zrb/issues). Please include your Zrb version (`zrb version`) and steps to reproduce the issue.
- **Contributions:** We love pull requests! See our [contribution guidelines](https://github.com/state-alchemists/zrb/pulls) to get started.
- **Support Zrb:** If you find Zrb valuable, please consider showing your support.
[](https://stalchmst.com)
---
## π 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)](https://garo.fandom.com/wiki/Zaruba)
Raw data
{
"_id": null,
"home_page": "https://github.com/state-alchemists/zrb",
"name": "zrb",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.10.0",
"maintainer_email": null,
"keywords": "Automation, Task Runner, Code Generator, Monorepo, Low Code",
"author": "Go Frendi Gunawan",
"author_email": "gofrendiasgard@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5f/fc/e0984582fe0cc61398f4bd942857c5d62a921d6bc716f73b0a62b6237cdb/zrb-1.10.2.tar.gz",
"platform": null,
"description": "\n\n# \ud83e\udd16 Zrb: Your Automation Powerhouse\n\n**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.\n\nWhether 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.\n\n[Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [Contribution Guidelines](https://github.com/state-alchemists/zrb/pulls) | [Report an Issue](https://github.com/state-alchemists/zrb/issues)\n\n---\n\n## \ud83d\udd25 Why Choose Zrb?\n\nZrb is designed to be powerful yet intuitive, offering a unique blend of features:\n\n- \ud83e\udd16 **Built-in LLM Integration:** Go beyond simple automation. Leverage Large Language Models to generate code, create diagrams, produce documentation, and more.\n- \ud83d\udc0d **Pure Python:** Write your tasks in Python. No complex DSLs or YAML configurations to learn.\n- \ud83d\udd17 **Smart Task Chaining:** Define dependencies between tasks to build sophisticated, ordered workflows.\n- \ud83d\udcbb **Dual-Mode Execution:** Run tasks from the command line for speed or use the built-in web UI for a more visual experience.\n- \u2699\ufe0f **Flexible Configuration:** Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or `.env` files.\n- \ud83d\udde3\ufe0f **Cross-Communication (XCom):** Allow tasks to safely exchange small pieces of data.\n- \ud83c\udf0d **Open & Extensible:** Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.\n\n---\n\n## \ud83d\ude80 Quick Start: Your First AI-Powered Workflow in 5 Minutes\n\nLet'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.\n\n### 1. Prerequisites: Get Your Tools Ready\n\nBefore you start, make sure you have the following:\n\n- **An LLM API Key:** Zrb needs an API key to talk to an AI model.\n ```bash\n export OPENAI_API_KEY=\"your-key-here\"\n ```\n > Zrb defaults to OpenAI, but you can easily configure it for other providers like **Deepseek, Ollama, etc.** See the [LLM Integration Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/configuration/llm-integration.md) for details.\n\n- **Mermaid CLI:** This tool converts Mermaid diagram scripts into images.\n ```bash\n npm install -g @mermaid-js/mermaid-cli\n ```\n\n### 2. Install Zrb\n\nThe easiest way to get Zrb is with `pip`.\n\n```bash\npip install zrb\n# Or for the latest pre-release version:\n# pip install --pre zrb\n```\n\nAlternatively, you can use an installation script that handles all prerequisites:\n```bash\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/state-alchemists/zrb/main/install.sh)\"\n```\n\n> For other installation methods, including **Docker \ud83d\udc0b** and **Android \ud83d\udcf1**, check out the full [Installation Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/README.md).\n\n### 3. Define Your Tasks\n\nCreate a file named `zrb_init.py` in your project directory. Zrb automatically discovers this file.\n\n> **\ud83d\udca1 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!\n\nAdd the following Python code to your `zrb_init.py`:\n\n```python\nfrom zrb import cli, LLMTask, CmdTask, StrInput, Group\nfrom zrb.builtin.llm.tool.code import analyze_repo\nfrom zrb.builtin.llm.tool.file import write_to_file\n\n\n# Create a group for Mermaid-related tasks\nmermaid_group = cli.add_group(Group(\n name=\"mermaid\",\n description=\"\ud83e\udddc Mermaid diagram related tasks\"\n))\n\n# Task 1: Generate a Mermaid script from your source code\nmake_mermaid_script = mermaid_group.add_task(\n LLMTask(\n name=\"make-script\",\n description=\"Create a mermaid diagram from source code in the current directory\",\n input=[\n StrInput(name=\"dir\", default=\"./\"),\n StrInput(name=\"diagram\", default=\"state-diagram\"),\n ],\n message=(\n \"Read all necessary files in {ctx.input.dir}, \"\n \"make a {ctx.input.diagram} in mermaid format. \"\n \"Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`\"\n ),\n tools=[\n analyze_repo, write_to_file\n ],\n )\n)\n\n# Task 2: Convert the Mermaid script into a PNG image\nmake_mermaid_image = mermaid_group.add_task(\n CmdTask(\n name=\"make-image\",\n description=\"Create a PNG from a mermaid script\",\n input=[\n StrInput(name=\"dir\", default=\"./\"),\n StrInput(name=\"diagram\", default=\"state-diagram\"),\n ],\n cmd=\"mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'\",\n cwd=\"{ctx.input.dir}\",\n )\n)\n\n# Set up the dependency: the image task runs after the script is created\nmake_mermaid_script >> make_mermaid_image\n```\n\n### 4. Run Your Workflow!\n\nNow, navigate to any project with source code. For example:\n\n```bash\ngit clone git@github.com:jjinux/gotetris.git\ncd gotetris\n```\n\nRun your new task to generate the diagram:\n\n```bash\nzrb mermaid make-image --diagram \"state-diagram\" --dir ./\n```\n\nYou can also run it interactively and let Zrb prompt you for inputs:\n```bash\nzrb mermaid make-image\n```\nZrb will ask for the directory and diagram name\u2014just press **Enter** to accept the defaults.\n\nIn moments, you'll have a beautiful state diagram of your code!\n\n\n\n---\n\n## \ud83d\udda5\ufe0f Try the Web UI\n\nPrefer a graphical interface? Zrb has you covered. Start the web server:\n\n```bash\nzrb server start\n```\n\nThen open your browser to `http://localhost:21213` to see your tasks in a clean, user-friendly interface.\n\n\n\n---\n\n## \ud83d\udcac Interact with an LLM Directly\n\nZrb brings AI capabilities right to your command line.\n\n### Interactive Chat\n\nStart a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.\n\n```bash\nzrb llm chat\n```\n\n### Quick Questions\n\nFor a single question, use the `ask` command for a fast response.\n\n```bash\nzrb llm ask \"What is the capital of Indonesia?\"\n```\n\n---\n\n## \ud83c\udfa5 Demo & Documentation\n\n- **Dive Deeper:** [**Explore the Full Zrb Documentation**](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)\n- **Watch the Video Demo:**\n\n [](https://www.youtube.com/watch?v=W7dgk96l__o)\n\n---\n\n## \ud83e\udd1d Join the Community & Support the Project\n\n- **Bugs & Feature Requests:** Found a bug or have a great idea? [Open an issue](https://github.com/state-alchemists/zrb/issues). Please include your Zrb version (`zrb version`) and steps to reproduce the issue.\n- **Contributions:** We love pull requests! See our [contribution guidelines](https://github.com/state-alchemists/zrb/pulls) to get started.\n- **Support Zrb:** If you find Zrb valuable, please consider showing your support.\n\n [](https://stalchmst.com)\n\n---\n\n## \ud83c\udf89 Fun Fact\n\n**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.\n\n> *Madou Ring Zaruba (\u9b54\u5c0e\u8f2a\u30b6\u30eb\u30d0, Mad\u014drin Zaruba) is a Madougu which supports bearers of the Garo Armor.* [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba)\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "Your Automation Powerhouse",
"version": "1.10.2",
"project_urls": {
"Documentation": "https://github.com/state-alchemists/zrb",
"Homepage": "https://github.com/state-alchemists/zrb",
"Repository": "https://github.com/state-alchemists/zrb"
},
"split_keywords": [
"automation",
" task runner",
" code generator",
" monorepo",
" low code"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "035b277489b3dbde1ceed3f7085030238dce0cd5ba12db881ed61ebd2a1a4a33",
"md5": "294f8a9f7e78fd7b4d7b93993a6654e8",
"sha256": "417af0fed9b4759733ffbc7562a0fffa2ccb10f1c7977a5944346e3ce3a96d5c"
},
"downloads": -1,
"filename": "zrb-1.10.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "294f8a9f7e78fd7b4d7b93993a6654e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.10.0",
"size": 881513,
"upload_time": "2025-07-18T09:25:56",
"upload_time_iso_8601": "2025-07-18T09:25:56.117854Z",
"url": "https://files.pythonhosted.org/packages/03/5b/277489b3dbde1ceed3f7085030238dce0cd5ba12db881ed61ebd2a1a4a33/zrb-1.10.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ffce0984582fe0cc61398f4bd942857c5d62a921d6bc716f73b0a62b6237cdb",
"md5": "906ddd07a00ddd7eb6f07ff833ef91c1",
"sha256": "46d8aae80cb49c663634a907aeea7a4df8b7bbd4d70d440a20d7969de01f793b"
},
"downloads": -1,
"filename": "zrb-1.10.2.tar.gz",
"has_sig": false,
"md5_digest": "906ddd07a00ddd7eb6f07ff833ef91c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.10.0",
"size": 727834,
"upload_time": "2025-07-18T09:25:58",
"upload_time_iso_8601": "2025-07-18T09:25:58.682554Z",
"url": "https://files.pythonhosted.org/packages/5f/fc/e0984582fe0cc61398f4bd942857c5d62a921d6bc716f73b0a62b6237cdb/zrb-1.10.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 09:25:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "state-alchemists",
"github_project": "zrb",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "zrb"
}
JSON
