bun-simplcli

v1.5.0

Published

3 months ago

Comprehensive zero-dependency headless console & RAD toolkit for Bun with rich UI, telemetry, redis, and 54 CLI tools

0High
0Medium
0Low

codecaine

bun cli terminal console rad redis namespaced-redis prompts tables spinners sparklines telemetry zero-dependencies

SimpleCLI: Headless Console & RAD Toolkit for Bun

SimpleCLI for Bun is a comprehensive, lightweight, zero-dependency console utility framework and Rapid Application Development (RAD) toolkit built natively for the Bun JavaScript/TypeScript runtime.

It delivers cross-platform OS system telemetry, hardware resource monitoring, desktop notifications, speech synthesis, standard path resolvers, high-speed cryptography (via Bun.CryptoHasher and Bun.password), native namespaced multi-tenant Redis, interactive prompts (select, multi-select, fuzzy search, form wizards), multi-step task pipelines with animated spinners, structured multi-level logging, CLI flag parsing, and a complete suite of 54 pre-built production CLI applications.

🎬 Live Demos & Terminal Recordings

🧮 Mathematics & Scientific Computing Suite

SimpleCLI Mathematics Suite

🔴 Multi-Tenant Namespaced Redis Manager

Namespaced Redis Showcase

🚀 Bun SimpleCLI Full Showcase

Bun SimpleCLI Showcase

📼 Recording Your Own Demos with VHS

You can re-render all VHS tapes using the built-in scripts:

# Render all VHS tape scripts to assets/
vhs scripts/tapes/math_suite.tape
vhs scripts/tapes/bun_simplcli_showcase.tape
vhs scripts/tapes/kalker.tape
vhs scripts/tapes/calc.tape
vhs scripts/tapes/stats.tape
vhs scripts/tapes/graph.tape
vhs scripts/tapes/crypto.tape
vhs scripts/tapes/redis.tape


# Or run the live demonstration shell script
./scripts/demo_showcase.sh
./scripts/math_showcase.sh

📑 Table of Contents

✨ Features

🚀 Zero External Runtime Dependencies: 100% native Bun APIs and modern TypeScript standard library.
🎨 Rich RAD Console UI: Framed panels, Unicode data tables, ASCII banners, status badges, GitHub-style alert boxes, sparklines, meter gauges, hierarchical trees, and colored line diffs.
🎛️ Interactive Terminal Prompts: Keyboard arrow-navigated single/multi-select menus, live fuzzy search, masked password prompts, email/URL validators, and multi-field form wizards.
⚡ Multi-Step Pipelines: Chained workflow execution with step spinners, precise timers, and summary reporting.
🪵 Structured Multi-Level Logging: Trace, Debug, Info, Success, Warn, Error, and Fatal logging with automatic timestamps and file streaming.
📊 Hardware & Telemetry: CPU load averages, RAM allocation, disk capacity, Wi-Fi SSID, network IP addresses, and TCP port scanner.
🔒 Security & Cryptography: Native SHA-256/512/MD5, AES-256-CBC encryption/decryption, HMAC, native BCrypt/Argon2 (via Bun.password), and UUID v4 / UUID v7.
🌐 HTTP & Networking: REST API client with status codes, headers, and file downloads with live progress bars.
📦 Generic Data Structures: Stack, Queue, SetCollection, RingBuffer, MinHeap, PriorityQueue, and LRUCache.
🧮 Statistics & Math: Mean, median, mode, standard deviation, RMS, variance, and numeric aggregations.
🔴 Native Namespaced Redis Wrapper: Multi-tenant key isolation, typed JSON, sub-namespaces, hashes, sets, distributed locks, and pub/sub.
🛠️ 54 Pre-Built Production CLI Tools: Ready-to-run utilities for DevOps, security, databases, text processing, media, and mathematics.

📦 Installation & Setup

Install as a Library in Your Project

# Using Bun (Recommended)
bun add bun-simplcli

# Using npm
npm install bun-simplcli

Install Globally as a CLI Suite (54 Tools)

# Global CLI installation
bun add -g bun-simplcli

# Or run instantly with bunx without installing:
bunx bun-simplcli
bunx simplcli --list

Local Development & Source Setup

# Clone the repository
git clone https://github.com/codecaine-zz/bun_simplcli.git
cd bun_simplcli

# Run tests
bun test

# Launch the unified CLI suite
bun run start

Homebrew & Subprocess Dependencies Setup

While the core SimpleCLI library is 100% zero-dependency, certain pre-built CLI applications in cli_apps/ leverage external system utilities (e.g. ffmpeg, ripgrep, fd, jq, redis, imagemagick, tesseract, pandoc, vhs, qalc, numbat, kalker, nmap) via fast subprocess execution.

An automated dependency installer script is included to install Homebrew (if missing) and all required toolchains:

# Check existing tool status without installing
bun run check:deps
# or: ./scripts/install_dependencies.sh --check

# Interactive setup wizard
bun run setup:brew
# or: ./scripts/install_dependencies.sh

# Install all dependencies for all 54 CLI tools + VHS recordings
bun run setup:brew:all
# or: ./scripts/install_dependencies.sh --all

Selective Installation Profiles:

# Install core essentials (ripgrep, fd, jq, ffmpeg, redis)
./scripts/install_dependencies.sh --essential

# Install media & OCR processing tools (ffmpeg, yt-dlp, imagemagick, tesseract, exiftool, id3v2)
./scripts/install_dependencies.sh --media

# Install scientific & calculus tools (libqalculate, numbat, kalker)
./scripts/install_dependencies.sh --math

# Install network reconnaissance & security tools (nmap, subfinder)
./scripts/install_dependencies.sh --security

# Install terminal GIF recorder & tape generator (vhs, ttyd)
./scripts/install_dependencies.sh --vhs

🚀 Quick Start

import { SimpleCLI } from 'bun-simplcli';

const app = SimpleCLI.newApp('DeployPilot', '1.0.0')
  .setDescription('Cloud Infrastructure Deployment Automation');

// Define CLI Flags
app.addFlagString('env', 'e', 'staging', 'Target deployment environment (staging|prod)');
app.addFlagInt('port', 'p', 8080, 'Listening port number');
app.addFlagBool('dry-run', 'd', false, 'Simulate deployment without modifying resources');

if (!app.parseCli()) process.exit(0);

const targetEnv = app.getFlagString('env');
const isDryRun = app.getFlagBool('dry-run');

app.banner('DeployPilot Cloud Runner', `Target: ${targetEnv}`);

app.step(1, 'Validating Credentials');
app.success('Authentication tokens verified');

app.step(2, 'Running Infrastructure Pipeline');
const pipeline = app.newPipeline('Deployment Stages');
pipeline.addStep('Provision compute instances', async () => true);
pipeline.addStep('Apply database migrations', async () => true);
pipeline.addStep('Configure load balancer routes', async () => true);
await pipeline.run();

app.panel('Status Summary', `All deployment stages completed successfully on ${targetEnv}.`);

🖥️ Console UI & RAD Components

Formatted Tables & Key-Value Pairs

// Aligned Key-Value Dictionary
app.printKv({
  'Host Name': 'srv-prod-api-01',
  'IP Address': '10.0.4.18',
  'Architecture': 'aarch64 (Apple Silicon)',
  'Uptime': '14 days, 6 hours',
});

// Formatted Data Grid with Borders
app.table(
  ['Endpoint', 'Protocol', 'Latency', 'Status'],
  [
    ['https://api.internal/v1', 'HTTP/2', '12.4 ms', '200 OK'],
    ['https://auth.internal', 'HTTP/2', '8.1 ms', '200 OK'],
    ['postgres://10.0.0.5:5432', 'TCP', '1.2 ms', 'CONNECTED'],
    ['redis://10.0.0.9:6379', 'TCP', '0.4 ms', 'CONNECTED'],
  ]
);

Sparklines & Bar Charts

// Unicode Inline Sparkline
const latencies = [12.0, 15.0, 45.0, 90.0, 120.0, 80.0, 30.0, 14.0];
const spark = app.sparkline(latencies);
app.info(`Latency Trend: ${spark}`); // ▂▄▆█▆▂ 

// Horizontal Bar Chart
app.barChart('Resource Allocation (%)', {
  'CPU Core 0': 42.5,
  'CPU Core 1': 89.0,
  'Memory': 64.2,
  'Disk /': 23.8,
}, 30);

Interactive Menus & Prompts

// Arrow-key single select
const env = await app.select('Choose build target environment:', [
  'Local Development',
  'Staging Integration',
  'Production Release',
]);

// Live fuzzy search selector
const branch = await app.fuzzySelect('Search Git branch:', [
  'main',
  'feature/rad-components',
  'feature/graphql-api',
  'bugfix/state-persistence',
]);

// Masked secret prompt
const apiToken = await app.promptPassword('Enter secret API access token:');

🛠️ Complete Suite of 54 CLI Applications

Run any tool directly via bun run bin/simplcli.ts <app-name> or run individual scripts in cli_apps/:

🧩 Subprocess Engine Dependency Map

For CLI applications that interface with external engines via subprocesses, the corresponding Homebrew formulas can be installed individually or in bulk via ./scripts/install_dependencies.sh --all:

🧪 Running Tests & Building

# Run all unit tests
bun test

# Generate shell completions for zsh, bash, or fish
bun run bin/simplcli.ts completion zsh

# Compile any CLI tool to a standalone zero-dependency executable
bun run bin/simplcli.ts compile jwt_cli ./dist/jwt-bin