Zirv CLI is a cross-platform command-line interface for developers to automate and streamline workflows with YAML, JSON, or TOML scripts.

• Features
• Installation
• Usage
  • Initialize a Project
  • Running Scripts
  • Passing Parameters & Secrets
  • Capture Output
  • Failure Hooks
  • Chaining Scripts
• Configuration
  • Directory Structure
  • Schema Examples
• Shortcuts
• Supported Platforms
• Contribution
• License
• Contact

• YAML-Driven Scripts: Define commands in .zirv/ files with metadata (name, description, params, secrets).
• Capture Output: Use capture: var_name on any step to grab its stdout into ${var_name} for later substitution.
• Failure Hooks: On a step failure you can declare an fallback sub-chain of commands, then retry the original step once.
• Flexible Options: Interactive mode, OS filters, proceed_on_failure, delays, and secret support.
• Multi-Format: Supports YAML, JSON, and TOML—extendable.
• Cross-Platform: Compatible with Windows, macOS, and Linux.

Choose one of the following methods:

brew tap glubiz/homebrew-tap
brew install zirv

choco install zirv

Download the latest release from the [GitHub Releases]:

VERSION="1.0.0" && \
curl -L -o zirv.tar.gz "https://github.com/Glubiz/zirv-dynamic-cli/releases/download/${VERSION}/zirv-${VERSION}-linux.tar.gz" && \
tar -xzf zirv.tar.gz && \
sudo mv zirv /usr/local/bin/zirv && \
rm zirv.tar.gz && \
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc && \
source ~/.bashrc

# Build from source
cargo build --release
# Add `target/release` to your PATH

Download the latest release from the [GitHub Releases]: https://github.com/Glubiz/zirv-dynamic-cli/releases

Run:

zirv init

Creates a .zirv/ directory with a sample script. This directory is where you will define your scripts. The .zirv/ directory is created in the current working directory or in the HOME directory depending on the commandline interactions.

Place your script files in .zirv/ (e.g., build.yaml):

name: Build
description: Build the application.
commands:
  - command: cargo build --release
    options:
      proceed_on_failure: false
  - command: cargo test
    options:
      proceed_on_failure: false

Execute the script with:

zirv build

If a script declares parameters;

name: Commit Changes
params:
  - commit_message
commands:
  - command: git add .
  - command: git commit -m "${commit_message}"
  - command: git push origin

Run with:

zirv commit "Your commit message here"

To capture the output of a command, use the capture option:

name: Capture Test
commands:
  - command: "echo hello"
    capture: greeting
    options:
      proceed_on_failure: false
  - command: "echo Got: ${greeting}"

First step stores hello in the variable ${greeting}, which is then used in the second step to print Got: hello.

Declare a failure hook for a command using fallback:

name: OnFailure Demo
commands:
  - command: "sh -c 'exit 1'"
    options:
      proceed_on_failure: true     # continue even if retry also fails
      fallback:
        - command: "echo 'Fallback action'"

This will execute the fallback command if the first command fails. The original command will be retried once.

You can chain scripts by calling one script from another. For example, if you have a script build.yaml and want to call it from deploy.yaml:

name: Deploy
description: Deploy the application.
commands:
  - command: zirv test
    options:
      proceed_on_failure: false
  - command: zirv build
    options:
      proceed_on_failure: false

Run the deploy script with:

zirv deploy

You can open multiple terminals at once by nesting lists. For example:

name: Parallel Commands
commands:
  - - command: "echo 'Running Task A'"
    - command: "echo 'Running Task B'"
  - - command: "echo 'Running Task 1'"
    - command: "echo 'Running Task 2'"

Each nested list spawns its own shell window. Every window executes the commands listed in that group and stays open until they finish.

The built-in cd command updates the working directory for any following commands in the same window, allowing scripts like:

commands:
  - - command: "cd backend"
    - command: "cargo run"

The .zirv/ directory contains your scripts and a configuration file. The structure is as follows:

.zirv/
├── .shortcuts.yaml
├── ...command files

Supported schemas are YAML, JSON, and TOML. Below are examples of each:

name: Example Config
description: An example script.
params:
  - param1
commands:
  - command: "echo Welcome, ${user}"
    capture: welcome_msg
    options:
      interactive: false

  - command: echo ${welcome_msg}
    description: Prints greeting
    options:
      interactive: true
      os: linux
      proceed_on_failure: false
      delay_ms: 2000
      fallback:
        - command: "echo 'Attempting fallback...'"
secrets:
  - name: api_key
    env_var: API_KEY

{
  "name": "Example Config",
  "description": "An example script.",
  "params": ["param1"],
  "commands": [
    {
      "command": "echo Welcome, ${user}",
      "capture": "welcome_msg",
      "options": {
        "interactive": false
      }
    },
    {
      "command": "echo ${welcome_msg}",
      "description": "Prints greeting",
      "options": {
        "interactive": true,
        "os": "linux",
        "proceed_on_failure": false,
        "delay_ms": 2000,
        "fallback": [
          {
            "command": "echo 'Attempting fallback...'"
          }
        ]
      }
    }
  ],
  "secrets": [
    {
      "name": "api_key",
      "env_var": "API_KEY"
    }
  ]
}

name = "Example Config"
description = "An example script."
params = ["param1"]

[[commands]]
command = "echo Welcome, ${user}"
capture = "welcome_msg"
options.interactive = false

[[commands]]
command = "echo Token is ${token}"
options.interactive = true
options.os = "linux"
options.proceed_on_failure = false
options.delay_ms = 2000

[[commands.options.fallback]]
command = "echo 'Attempting fallback...'"

[[secrets]]
name = "api"
env_var = "API_KEY"

Shortcuts are defined in .shortcuts.yaml and allow you to create aliases for your scripts. For example:

shortcuts:
  b: build.yaml
  t: test.yaml
  c: commit.yaml

Run zirv b instead of zirv build.yaml. This will execute the build.yaml script.

• Windows
• macOS
• Linux

Commands can target specific operating systems using the os option in the script configuration.

• windows: Windows OS
• linux: Linux OS
• macos: macOS

Contributions are welcome! Please fork the repository and submit a pull request with your changes. For major changes, please open an issue first to discuss what you would like to change.

Licensed under the MIT License.

Tweet @Glubiz