pypi package 'zrb'

Popularity: Low
Description: Your faithful companion
Installation: pip install zrb
Last version: 0.0.27 (Download)
Size: 66.25 kB
License: No license information provided


Last modified: February 22, 2023 1:06 AM (7 months ago)
Versions released in one year: 26
Weekly downloads: 3
01/22/202304/16/202307/02/202309/17/202302505007501,000036912released versions / week
  • Versions released
  • Weekly downloads


Zrb (WIP)

Your faithful companion.

How to install

pip install zrb

How to use

To run a task, you can invoke the following command:

zrb <task> [arguments]

Autoloaded tasks

Zrb will automatically load the following task definitions:

  • Every task definition in ZRB_INIT_SCRIPTS.
    • You can use a colon separator (:) to define multiple scripts in ZRB_INIT_SCRIPTS. For example:
  • Every task definition in in your current directory.
    • If Zrb cannot find any in your current directory, it will look at the parent directories until it finds one.
  • Every built-in task definition given ZRB_SHOULD_LOAD_BUILTIN equals 1 or unset.

How to define tasks

You can write your task definitions in Python. For example:

from zrb import (
    runner, Env,
    StrInput, ChoiceInput, IntInput, BoolInput, FloatInput, PasswordInput,
    Group, Task, CmdTask, HTTPChecker

# Simple Python task.
# Usage example: zrb concat --separator=' '
concat = Task(
    name='concat',  # Task name
    inputs=[StrInput(name='separator', description='Separator', default=' ')],
    run=lambda *args, **kwargs: kwargs.get('separator', ' ').join(args)

# Simple Python with multiple inputs.
register_trainer = Task(
        StrInput(name='name', default=''),
        PasswordInput(name='password', default=''),
        IntInput(name='age', default=0),
        BoolInput(name='employed', default=False),
        FloatInput(name='salary', default=0.0),
            choices=['bulbasaur', 'charmender', 'squirtle']
    run=lambda *args, **kwargs: kwargs

# Simple CLI task.
# Usage example: zrb hello --name='world'
hello = CmdTask(
    inputs=[StrInput(name='name', description='Name', default='world')],
    cmd='echo Hello {{}}'

# Command group: zrb make
make = Group(name='make', description='Make things')

# CLI task, part of `zrb make` group, depends on `hello`
# Usage example: zrb make coffee
make_coffee = CmdTask(
    cmd='echo Coffee for you β˜•'

# CLI task, part of `zrb make` group, depends on `hello`
# Usage example: zrb make beer
make_beer = CmdTask(
    cmd='echo Cheers 🍺'

# Command group: zrb make gitignore
make_gitignore = Group(
    name='gitignore', description='Make gitignore', parent=make

# CLI task, part of `zrb make gitignore` group,
# making .gitignore for Python project
# Usage example: zrb make gitignore python
make_gitignore_python = CmdTask(
        'echo "node_modules/" >> .gitignore'
        'echo ".npm" >> .gitignore'
        'echo "npm-debug.log" >> .gitignore'

# CLI task, part of `zrb make gitignore` group,
# making .gitignore for Node.js project
# Usage example: zrb make gitignore node
make_gitignore_nodejs = CmdTask(
        'echo "__pycache__/" >> .gitignore'
        'echo "venv" >> .gitignore'

# Long running CLI task
# Usage example: zrb start-server dir='.'
start_server = CmdTask(
    upstreams=[make_coffee, make_beer],
    inputs=[StrInput(name='dir', description='Directory', default='.')],
    envs=[Env(name='PORT', os_name='WEB_PORT', default='3000')],
    cmd='python -m http.server $PORT --directory {{input.dir}}',

# CLI task, depends on `start-server`, throw error
# Usage example: zrb test-error
test_error = CmdTask(
    cmd='sleep 3 && exit 1',

Once registered, your task will be accessible from the terminal.

For example, you can run a server by performing:

export WEB_PORT=8080
zrb start-server

The output will be similar to this:

Name [world]: Go Frendi
Dir [.]:
πŸ€– ➜  2023-02-22T08:02:52.611040 βš™ 14426 ➀ 1 of 3 β€’ πŸ‹            zrb hello β€’ Hello Go Frendi
πŸ€– ➜  2023-02-22T08:02:52.719826 βš™ 14428 ➀ 1 of 3 β€’ 🍊      zrb make coffee β€’ Coffee for you β˜•
πŸ€– ➜  2023-02-22T08:02:52.720372 βš™ 14430 ➀ 1 of 3 β€’ πŸ’        zrb make beer β€’ Cheers 🍺
πŸ€– ➜  2023-02-22T08:02:52.845930 βš™ 14432 ➀ 1 of 3 β€’ 🍎     zrb start-server β€’ Serving HTTP on port 3000 ( ...
πŸ€– ➜  2023-02-22T08:02:52.910192 βš™ 14425 ➀ 1 of 1 β€’ 🍈           http-check β€’ HEAD http://localhost:3000/ 200 (OK)
Support zrb growth and development!
β˜• Donate at:
πŸ™ Submit issues/pull requests at:
🐀 Follow us at:
zrb start-server completed in 1.681591272354126 seconds
πŸ€– ⚠  2023-02-22T08:02:52.911657 βš™ 14432 ➀ 1 of 3 β€’ 🍎     zrb start-server β€’ - - [22/Feb/2023 08:02:52] "HEAD / HTTP/1.1" 200 -

How to run tasks programmatically

To run a task programmatically, you need to create a main loop.

For example:

from zrb import CmdTask

cmd_task = CmdTask(
    cmd='echo hello'
main_loop = cmd_task.create_main_loop(env_prefix='')
result = main_loop() # This run the task
print(result.output) # Should be "hello"

Enable shell completion

To enable shell completion, you need to set _ZRB_COMPLETE variable.

For bash:

eval $(_ZRB_COMPLETE=bash_source zrb)

For zsh:

eval $(_ZRB_COMPLETE=zsh_source zrb)

Once set, you will have a shell completion in your session:

zrb <TAB>
zrb md5 hash -<TAB>

Visit click shell completion for more information.


The following configurations are available:

  • ZRB_HOME_DIR: Zrb home directory.
    • Default: Zrb home directory
  • ZRB_LOGGING_LEVEL: Logging verbosity.
    • Default: WARNING
    • Possible values:
      • CRITICAL
      • ERROR
      • WARNING
      • WARN (The same as WARNING)
      • INFO
      • DEBUG
      • NOTSET
  • ZRB_INIT_SCRIPTS: List of task registration script that should be loaded by default.
    • Default: Empty
    • Possible values: List of script paths, separated by colons(:).
    • Example: ~/personal/
  • ZRB_ENV: Environment prefix that will be used when loading Operating System's environment.
    • Default: Empty
    • Possible values: Any combination of alpha-numeric and underscore
    • Example: DEV
  • ZRB_SHOULD_LOAD_BUILTIN: Whether load builtin tasks or not
    • Default: 1
    • Possible values:
      • 1
      • 0
  • ZRB_SHELL: Default shell for running cmdTask
    • Default: bash
    • Possible value:
      • /usr/bin/bash
      • /usr/bin/sh
      • node
      • python
  • ZRB_SHOW_ADVERTISEMENT: Whether show advertisement or not.
    • Default: 1
    • Possible value:
      • 1
      • 0


  • No one is sure how to pronounce Zrb. Let's keep it that way.
  • If not set, PYTHONUNBUFFERED will be set to 1.
  • Once is loaded, Zrb will automatically:
    • Set ZRB_PROJECT_DIR to's parent directory.
    • If loaded as CLI, Zrb will also:
  • Zrb passes several keyword arguments that will be accessible from the task's run method:
    • _args: Shell argument when the task is invoked.
    • _task: Reference to the current task.
  • You can access the built-in command groups by importing zrb.builtin_group.

For contributors

There is a toolkit you can use to test whether Zrb is working as intended.

To use the toolkit, you can invoke the following command:

source ./

Once you load the toolkit, you can start playing around.

# Run test and serve coverage.
zrb test

# Test zrb in playground
zrb prepare-playground

For maintainers

To publish Zrb, you need a Pypi account:

You can also create a TestPypi account:

Once you have your API token, you need to create a ~/.pypirc file:

index-servers =

  repository =
  username = __token__
  password = pypi-xxx-xxx
  repository =
  username = __token__
  password = pypi-xxx-xxx

To publish Zrb, you can do the following:

source ./

# Publish Zrb to TestPypi
zrb publish-test

# Publish Zrb to Pypi
zrb publish