bzy

Bzync Automation CLI

A lightweight, zero-dependency Bash automation CLI for remote command execution, Docker orchestration, file synchronization, system operations, and infrastructure automation.

bzy is designed for Bzync infrastructure and development workflows where commands should be safe, observable, reproducible, and auditable.

Features

Zero-dependency runtime — implemented entirely in Bash with set -Eeuo pipefail
Remote execution over SSH — use existing SSH aliases or user@host targets
Rsync synchronization — simple pull and push workflows with progress
Remote Docker management — containers, images, and Compose stacks
Interactive confirmation — destructive operations require confirmation
Command progress — operations provide visible execution progress
Per-command audit logs — every invocation gets its own log file
Automatic secret redaction — sensitive values are masked before being written to logs
Persistent configuration — global rules and timezone settings are stored under ~/.bzy/
Temporary runtime rules — --exclude and --include can be applied to individual commands
Dry-run support — inspect operations before making changes
Timezone-aware logging — configure the timezone used by audit logs
Global installation — install bzy into your system PATH
MIT licensed

Installation

1. Clone or copy bzy

Place the script somewhere in your working directory:

mkdir -p ~/bzy
cd ~/bzy

For example:

~/bzy/
├── cli.sh
├── config
└── logs/

2. Make the CLI executable

chmod +x cli.sh

3. Configure the timezone

Set the default timezone used by bzy:

./cli.sh --tz-set Asia/Manila

The configuration is stored in:

~/.bzy/config

4. Install globally

Install bzy into /usr/local/bin:

./cli.sh service install

After installation:

bzy --help

5. Remove the global installation

bzy service uninstall

Configuration

bzy stores persistent configuration under:

~/.bzy/

The directory contains:

~/.bzy/
├── config
└── logs/

Configuration can be changed through CLI flags instead of manually editing the file.

Timezone

Set the persistent timezone:

bzy --tz-set Asia/Manila

Override the timezone for one execution:

bzy --tz America/New_York docker ps cloud

The persistent timezone remains unchanged.

Global Exclusions

Add a persistent rsync exclusion:

bzy --exclude-add node_modules/

Add multiple exclusions:

bzy --exclude-add node_modules/
bzy --exclude-add .git/
bzy --exclude-add "*.tmp"

Remove an exclusion:

bzy --exclude-rm node_modules/

Global Inclusions

Add a persistent inclusion pattern:

bzy --include-add "*.pdf"

Remove an inclusion pattern:

bzy --include-rm "*.pdf"

Temporary Rules

Temporary rules apply only to the current command.

Exclude .log files:

bzy --exclude "*.log" push cloud ./app /srv/app/

Include PDF files:

bzy --include "*.pdf" push cloud ./documents /srv/documents/

Temporary rules do not modify ~/.bzy/config.

Configuration File

The default configuration is stored at:

~/.bzy/config

Example:

TIMEZONE="Asia/Manila"

EXCLUDE="node_modules/"
EXCLUDE=".git/"
EXCLUDE="*.tmp"

INCLUDE="*.pdf"

Persistent configuration is automatically applied to supported commands.

Usage

General syntax:

bzy [global options] <command> [arguments]

Example:

bzy docker ps cloud

Global Options

Option	Description
`-y`, `--yes`	Skip confirmation prompts
`--dry-run`	Simulate an operation without making changes
`--no-progress`	Suppress progress output
`--tz <timezone>`	Override the log timezone for the current run
`--exclude <pattern>`	Add a temporary exclusion pattern
`--include <pattern>`	Add a temporary inclusion pattern
`-q`, `--quiet`	Reduce console output
`-h`, `--help`	Show help
`-v`, `--version`	Show version

File Synchronization

bzy uses rsync for efficient file synchronization.

Pull

Copy files from a remote host to the local machine:

bzy pull user@remote-host /var/www/remote-dir ./local-dir

Direction:

REMOTE → LOCAL

Example:

bzy pull cloud /srv/bzync ./backup/bzync

Push

Copy files from the local machine to a remote host:

bzy push user@remote-host ./local-app /var/www/remote-app

Direction:

LOCAL → REMOTE

Example:

bzy push cloud ./dist/ /srv/bzync/

Push with Temporary Exclusion

bzy --exclude "*.log" push cloud ./local-app /srv/remote-app/

Multiple temporary exclusions can be supplied:

bzy \
  --exclude node_modules/ \
  --exclude .git/ \
  --exclude "*.log" \
  push cloud ./local-app /srv/remote-app/

Docker

bzy manages Docker remotely through SSH.

No Bzync agent is required on the remote server.

Containers

List containers

bzy docker ps user@remote-host

Start a container

bzy docker start user@remote-host container_name

Stop a container

bzy docker stop user@remote-host container_name

Restart a container

bzy docker restart user@remote-host container_name

Inspect a container

bzy docker inspect user@remote-host container_name

View container logs

bzy docker logs user@remote-host container_name

Remove a container

bzy docker rm user@remote-host container_name

Destructive Docker operations require confirmation by default.

For automation:

bzy --yes docker restart user@remote-host container_name

Docker Images

List images

bzy docker image ls user@remote-host

Pull an image

bzy docker image pull user@remote-host nginx:latest

Inspect an image

bzy docker image inspect user@remote-host nginx:latest

Remove an image

bzy docker image rm user@remote-host nginx:latest

Image removal requires confirmation.

Docker Compose

Manage Compose projects using their remote project directory.

Start

bzy docker compose up user@remote-host /path/to/project

Start in background

bzy docker compose up user@remote-host /path/to/project --detach

Build and start

bzy docker compose up user@remote-host /path/to/project --build --detach

Stop

bzy docker compose down user@remote-host /path/to/project

Restart

bzy docker compose restart user@remote-host /path/to/project

Build

bzy docker compose build user@remote-host /path/to/project

Pull images

bzy docker compose pull user@remote-host /path/to/project

Service status

bzy docker compose ps user@remote-host /path/to/project

Service logs

bzy docker compose logs user@remote-host /path/to/project

bzy can detect common Compose filenames such as:

compose.yaml
compose.yml
docker-compose.yml

Remote Command Execution

Execute a command on a remote host:

bzy exec user@remote-host "docker ps"

Example:

bzy exec cloud "systemctl status nginx"

Another example:

bzy exec cloud "df -h"

All remote executions are recorded in the audit log.

System Operations

System information

bzy system info cloud

Disk usage

bzy system disk cloud

Memory

bzy system memory cloud

CPU

bzy system cpu cloud

Uptime

bzy system uptime cloud

Services

Manage systemd services remotely.

Status

bzy service status cloud nginx

Start

bzy service start cloud nginx

Stop

bzy service stop cloud nginx

Restart

bzy service restart cloud nginx

Enable

bzy service enable cloud nginx

Disable

bzy service disable cloud nginx

Operations that modify service state require confirmation.

Network

Interfaces

bzy network interfaces cloud

Public IP

bzy network ip cloud

Routes

bzy network routes cloud

Ping

bzy network ping cloud 10.10.0.1

Test port

bzy network port cloud 10.10.0.10 443

Processes

List processes

bzy process ps cloud

Inspect a process

bzy process inspect cloud 1234

Kill a process

bzy process kill cloud 1234

Process termination requires confirmation.

Git

Execute common Git operations inside a remote directory.

Status

bzy git status cloud /srv/project

Pull

bzy git pull cloud /srv/project

Push

bzy git push cloud /srv/project

Branch

bzy git branch cloud /srv/project

Log

bzy git log cloud /srv/project

Operations that modify the remote repository require confirmation.

Deployment

bzy provides deployment-oriented commands for remote application directories.

Deploy

bzy deploy cloud /srv/project

Update

bzy deploy update cloud /srv/project

Restart

bzy deploy restart cloud /srv/project

Rollback

bzy deploy rollback cloud /srv/project

Deployment operations require confirmation.

Backups

Create a backup

bzy backup create cloud /srv/application /srv/backups/application.tar.gz

Restore a backup

bzy backup restore cloud /srv/backups/application.tar.gz /srv/application

Restore operations require confirmation.

List backups

bzy backup list cloud /srv/backups

Health Checks

Check the general health of a remote host:

bzy health cloud

Check a service or container:

bzy health cloud nginx

Audit Logging

Every bzy invocation creates one dedicated log file.

Logs are stored under:

~/.bzy/logs/

Example:

~/.bzy/
└── logs/
    ├── 20260915-013142-481-docker-ps.log
    ├── 20260915-013205-902-docker-restart.log
    ├── 20260915-013411-127-push.log
    └── 20260915-013522-774-exec.log

Log Filename Format

YYYYMMDD-HHMMSS-mmm-command.log

For example:

20260915-013205-902-docker-restart.log

This makes every command execution independently identifiable.

Log Contents

Each execution log records:

execution date
execution time
command
target host
dry-run state
confirmation result
command output
command errors
final status
exit code
execution duration

Example:

DATE: 2026-09-15T01:32:05+08:00
COMMAND: bzy docker restart cloud bzync-cloud-server-1
TARGET: cloud
DRY RUN: no
CONFIRMATION: accepted

--- OUTPUT ---
Container bzync-cloud-server-1 restarted

--- END OUTPUT ---
END: 2026-09-15T01:32:07+08:00
STATUS: success
EXIT CODE: 0
DURATION: 2s

Secret Redaction

The audit engine automatically redacts common sensitive values before they are persisted to logs.

Examples of protected patterns include:

password
passwd
token
api_key
secret
authorization
Bearer tokens

Sensitive values are represented as:

********

The purpose is to make audit logs useful without unnecessarily storing credentials or authentication material.

Log Commands

List logs

bzy logs list

Show a specific log

bzy logs show 20260915-013205-902-docker-restart.log

Search/show logs by query

bzy logs show 2026

Follow the current log stream

bzy logs tail

Clear historical logs

bzy logs clear

Clearing logs requires confirmation.

Confirmation Model

Commands that can modify or destroy state require confirmation by default.

For example:

bzy docker stop cloud nginx

will prompt before execution.

For non-interactive automation, explicitly acknowledge the operation:

bzy --yes docker stop cloud nginx

This makes accidental destructive execution less likely while still supporting CI/CD and automation workflows.

Dry Run

Use --dry-run when supported to inspect an operation before making changes:

bzy --dry-run push cloud ./dist/ /srv/bzync/

Dry-run behavior is command-dependent.

Progress

Operations provide progress information by default.

Disable progress when integrating with another automation system:

bzy --no-progress push cloud ./dist/ /srv/bzync/

Reduce general console output:

bzy --quiet docker compose logs cloud /srv/bzync

Audit logging remains enabled even when --quiet or --no-progress is used.

Automation

bzy is designed to work both interactively and inside automation scripts.

Interactive:

bzy docker restart cloud bzync-cloud-server-1

Non-interactive:

bzy --yes docker restart cloud bzync-cloud-server-1

Dry-run:

bzy --dry-run deploy cloud /srv/bzync

Quiet automation:

bzy --yes --quiet --no-progress deploy cloud /srv/bzync

Design Principles

bzy follows a few simple principles:

Safe by default

Operations capable of changing system state should not silently execute.

Observable

Commands provide progress and retain their output.

Auditable

Every invocation receives its own persistent log.

Portable

The runtime is implemented in Bash and uses standard Unix tooling.

Remote-first

Existing SSH connectivity is used instead of requiring a separate remote agent.

Automation-friendly

Confirmation can be explicitly bypassed with --yes.

Configuration-driven

Persistent rules live under:

~/.bzy/config

while temporary rules remain local to a single invocation.

Directory Structure

Typical user-level installation:

~/.bzy/
├── config
└── logs/
    ├── 20260915-013142-481-docker-ps.log
    ├── 20260915-013205-902-docker-restart.log
    └── ...

Project source:

bzy/
├── cli.sh
└── README.md

License

Distributed under the MIT License.

Bzync

bzy is part of the Bzync open-source tooling ecosystem.

Name		Name	Last commit message	Last commit date
LICENSE		LICENSE
README.md		README.md
cli.sh		cli.sh

Latest commit

History

Folders and files

Repository files navigation

bzy

Features

Installation

1. Clone or copy bzy

2. Make the CLI executable

3. Configure the timezone

4. Install globally

5. Remove the global installation

Configuration

Timezone

Global Exclusions

Global Inclusions

Temporary Rules

Configuration File

Usage

Global Options

File Synchronization

Pull

Push

Push with Temporary Exclusion

Docker

Containers

List containers

Start a container

Stop a container

Restart a container

Inspect a container

View container logs

Remove a container

Docker Images

List images

Pull an image

Inspect an image

Remove an image

Docker Compose

Start

Start in background

Build and start

Stop

Restart

Build

Pull images

Service status

Service logs

Remote Command Execution

System Operations

System information

Disk usage

Memory

CPU

Uptime

Services

Status

Start

Stop

Restart

Enable

Disable

Network

Interfaces

Public IP

Routes

Ping

Test port

Processes

List processes

Inspect a process

Kill a process

Git

Status

Pull

Push

Branch

Log

Deployment

Deploy