bin/README.md

Utility Scripts Collection

Comprehensive collection of bash utility scripts for various tasks

This repository contains a curated collection of bash scripts for repository management, color manipulation, documentation generation, artifact handling, and more.

Table of Contents

• arty.sh - Repository and Release Management
• artifact_github_download.sh - GitHub Artifact Downloader
• artifact_postgres_export.sh - PostgreSQL Code Export
• css_color_filter.sh - CSS Filter Generator
• css_color_palette.sh - Color Palette Generator
• css_json_convert.sh - CSS Variable Converter
• doc_bash_generate.sh - Bash Documentation Generator
• doc_rust_generate.sh - Rust Documentation Generator
• jinja_template_render.sh - Jinja2 Template Renderer
• mime_mp4_gif.sh - MP4 to GIF Converter

---

arty.sh

A bash library repository and release management system

Combined functionality from arty.sh (repository management) and whip.sh (release cycle management).

Usage

arty <command> [arguments] [--dry-run] [-v|--verbose]

Commands

Repository Commands

• install <repo-url> [name] - Install a library from git repository
• deps [--dry-run] - Install all dependencies from arty.yml
• list - List installed libraries with dependency tree
• remove <name> - Remove an installed library
• init [name] - Initialize a new arty.yml project
• source <name> [file] - Source a library (for use in scripts)
• exec <lib-name> [args] - Execute a library's main script with arguments
• <script-name> - Execute a script defined in arty.yml

Release Commands

• release [major|minor|patch] - Full release workflow (default: patch)
  • Bumps version in arty.yml
  • Updates CHANGELOG.md from git history
  • Creates git commit
  • Creates and pushes git tag
• version - Show current version from arty.yml
• bump <major|minor|patch> - Bump version in arty.yml (no commit/tag)
• changelog - Generate changelog from git history
• tag <version> - Create and push git tag

Hook Commands

• hooks install - Install git commit hooks (includes shellcheck validation)
• hooks uninstall - Remove git commit hooks
• hooks create - Create default hook templates

Monorepo Commands

• mono list [root] [pattern] - List arty.yml projects
• mono version [root] [pattern] - Show versions of all projects
• mono bump <type> [root] [pattern] - Bump version for all projects
• mono status [root] [pattern] - Show git status for all projects
• mono exec <cmd> [root] [pattern] - Execute bash command on all projects
• mono help - Show detailed mono help

Examples

# Repository Management
arty install https://github.com/user/bash-utils.git
arty deps
arty list

# Release Cycle
arty release                    # Patch release
arty release major              # Major version release
arty bump minor                 # Just bump version
arty hooks install              # Install commit hooks

# Monorepo Management
arty mono list                  # List all projects
arty mono version               # Show all project versions
arty mono exec "git status"     # Run command on all projects

---

artifact_github_download.sh

GitHub Artifact Downloader

Download artifacts from GitHub Actions workflows with interactive selection or automatic matching.

Usage

artifact_github_download.sh <REPO> [OPTIONS]

Arguments

• REPO - GitHub repository (owner/repo)

Options

• -n, --name NAME - Artifact name to download (preselect)
• -o, --output DIR - Output directory (default: current directory)
• -h, --help - Show help message

Examples

# Interactive mode - list and select artifacts
artifact_github_download.sh valknarness/awesome

# Preselect artifact by name
artifact_github_download.sh valknarness/awesome -n awesome-database-latest

# Download to specific directory
artifact_github_download.sh valknarness/awesome -o ~/downloads

---

artifact_postgres_export.sh

Export code artifacts from Open WebUI PostgreSQL database

Extract code artifacts from chat conversations stored in PostgreSQL, preserving directory structure and file names.

Usage

artifact_postgres_export.sh [OPTIONS] <chat_id> <output_dir>

Arguments

• chat_id - Chat ID from Open WebUI URL (UUID format)
• output_dir - Directory to save extracted code files

Options

• -H, --host HOST - PostgreSQL host (default: ai_postgres via Docker)
• -u, --user USER - PostgreSQL user (default: ai)
• -d, --db DATABASE - PostgreSQL database (default: openwebui)
• -v, --verbose - Verbose output
• --remote HOST - SSH remote host for Docker access (default: vps)
• -f, --force - Force export even if output directory is not empty

Features

• Direct PostgreSQL access via Docker exec (SSH-enabled for remote servers)
• Automatic filename detection from markdown headers
• Directory structure preservation - maintains original paths
• Safety checks - validates chat ID format and checks for empty output directory
• Smart code extraction - parses markdown code blocks with language detection
• File extension mapping - supports 20+ file types

Examples

# Export chat to local directory
artifact_postgres_export.sh e135d74e-5b43-4b24-a651-e999f103942b ~/Projects/rust/piglet

# Export from remote server
artifact_postgres_export.sh --remote vps abc123def456 ./output

# Force export to non-empty directory
artifact_postgres_export.sh -f e135d74e-5b43-4b24-a651-e999f103942b ./output

---

css_color_filter.sh

CSS Color Filter Generator

Generate CSS filter values to transform black elements into any target color using SPSA optimization.

Usage

css_color_filter.sh [OPTIONS] [COLOR]

Arguments

• COLOR - Hex color (e.g., #FF0000, ff0000) or RGB (e.g., 255,0,0)

Options

• -i, --interactive - Interactive mode with colored preview
• -r, --raw - Output only the CSS filter (for piping)
• -c, --copy - Copy result to clipboard automatically
• -h, --help - Show help message

Examples

css_color_filter.sh "#FF5733"
css_color_filter.sh ff5733
css_color_filter.sh "255,87,51"
css_color_filter.sh -i

Algorithm

Uses SPSA (Simultaneous Perturbation Stochastic Approximation) to find optimal filter combinations that minimize color difference in RGB and HSL color spaces.

Dependencies

• bc - For floating-point arithmetic
• jq - For JSON formatting (optional)

---

css_color_palette.sh

CSS Color Palette Generator (Pure Bash)

Generate comprehensive color palettes without Node.js dependencies. Supports multiple harmony types and color scales.

Usage

css_color_palette.sh COLOR [OPTIONS]

Arguments

• COLOR - Base hex color (e.g., #3498db, 3498db)

Options

• -p, --palette TYPE - Palette type: monochromatic, analogous, complementary, split-complementary, triadic, tetradic
• -o, --output FILE - Output file (default: ./colors.yaml)
• -m, --mode MODE - Color mode: light, dark (default: light)
• -s, --style STYLE - Style: shades, tints, tones, all (default: all)
• -n, --name NAME - Palette name (default: auto-generated)
• --scales N - Number of scale steps (default: 11)
• -i, --interactive - Interactive mode
• -v, --verbose - Verbose output with color preview

Examples

css_color_palette.sh "#3498db"
css_color_palette.sh "#3498db" -p triadic -o palette.json
css_color_palette.sh "ff5733" -p analogous -m dark

Dependencies

• bc - For floating-point arithmetic

---

css_json_convert.sh

CSS Variable to JSON/YAML Converter

Extract CSS custom properties (variables) from a CSS file and convert them to JSON or YAML format.

Usage

css_json_convert.sh [OPTIONS] <input.css>

Arguments

• <input.css> - Input CSS file containing CSS variables

Options

• -o, --output FILE - Output file path (default: ./output.yaml)
• -c, --camel-case - Convert variable names to camelCase
• -v, --verbose - Enable verbose output
• -h, --help - Show help message

Examples

# Extract CSS vars to YAML (default)
css_json_convert.sh styles.css

# Extract to JSON with custom output
css_json_convert.sh styles.css -o theme.json

# Convert variable names to camelCase
css_json_convert.sh styles.css -o vars.json --camel-case

---

doc_bash_generate.sh

Bash Documentation Generator with Animated GIFs

Generate comprehensive README.md files with embedded asciinema GIFs for bash scripts.

Usage

doc_bash_generate.sh [OPTIONS] <executable> [executable...]

Arguments

• executable - One or more executables or glob patterns

Options

• -o, --output FILE - Output README.md path (default: ./README.md)
• -t, --title TITLE - Documentation title (default: auto-generated)
• --no-gif - Skip GIF generation (faster, text only)
• --gif-only - Only generate GIFs, don't update README
• -h, --help - Show help message

Examples

doc_bash_generate.sh css_*.sh
doc_bash_generate.sh -o docs/README.md *.sh
doc_bash_generate.sh --title "My Awesome Tools" script1.sh script2.sh

Dependencies

• asciinema - Terminal session recorder
• agg - Asciinema to GIF converter (cargo install agg)

---

doc_rust_generate.sh

Rust Documentation Generator with Custom Themes

Generate beautiful Rust documentation with custom color schemes and styling.

Usage

doc_rust_generate.sh [OPTIONS] <inputs...>

Arguments

• <inputs> - Input file(s) or pattern(s) to document:
  • Rust project directories (containing Cargo.toml)
  • Individual .rs files
  • Markdown files (.md)
  • JSON/TOML configuration files
  • Glob patterns (e.g., src/**/*.rs)

Options

• -o, --output DIR - Output directory for generated docs (default: $PWD/output)
• -c, --color COLOR - Primary accent color (hex format, default: #ff69b4)
• -s, --style STYLE - Background style theme: slate, zinc, neutral, stone, gray (default: slate)
• --font-sans FONT - Google Font for body text (default: Inter)
• --font-mono FONT - Google Font for code blocks (default: JetBrains Mono)
• --serve - Start HTTP server after generation
• --open - Open documentation in browser (implies --serve)
• -p, --port PORT - Port for HTTP server (default: 8000)
• -v, --verbose - Enable verbose output
• -d, --dry-run - Show what would be done without executing

Examples

# Generate docs for current Rust project
doc_rust_generate.sh .

# Custom color scheme
doc_rust_generate.sh . -c "#3498db" -s zinc -o ./docs

# Document specific files
doc_rust_generate.sh src/lib.rs src/main.rs -o ./api-docs

# Use custom fonts
doc_rust_generate.sh . --font-sans "Roboto" --font-mono "Fira Code"

# Generate and open in browser
doc_rust_generate.sh . --open

Dependencies

• cargo, rustdoc, bc, yq, jq, python3 with jinja2

---

jinja_template_render.sh

Jinja2 Template Renderer - Ninja Edition

A sophisticated Jinja2 template rendering engine with support for multiple variable sources, glob patterns, and ninja-style operations.

Usage

jinja_template_render.sh [OPTIONS] <template> [template...]

Arguments

• <template> - Template file(s) to render (glob patterns supported)

Options

• -o, --output DIR - Output directory (default: ./output)
• -v, --var KEY=VALUE - Define template variable (can be used multiple times)
• -f, --file FILE - Load variables from JSON/YAML file (repeatable)
• -V, --verbose - Enable verbose ninja commentary
• -p, --preview - Preview rendered output without saving
• -s, --strict - Enable strict mode (fail on undefined variables)
• -d, --dry-run - Perform dry run without writing files
• -w, --watch - Watch templates and re-render on changes (experimental)

Examples

# Render single template with CLI variables
jinja_template_render.sh template.j2 -v name=Ninja -v level=Master

# Render multiple templates with YAML config
jinja_template_render.sh templates/*.j2 -f config.yaml -o dist/

# Render with multiple variable sources
jinja_template_render.sh app.j2 -f base.yaml -f env.json -v debug=true

# Preview without saving
jinja_template_render.sh template.j2 -f vars.yaml --preview --verbose

Dependencies

• Python 3 with jinja2 package
• jq (for JSON parsing)
• yq (for YAML parsing)

---

mime_mp4_gif.sh

Advanced MP4 to GIF Converter

Convert MP4 videos to animated GIFs with advanced frame extraction algorithms, interpolation functions, and magical effects.

Usage

mime_mp4_gif.sh [OPTIONS] INPUT_FILE [OUTPUT_FILE]

Arguments

• INPUT_FILE - Input MP4 video file (required)
• OUTPUT_FILE - Output GIF file (optional, defaults to INPUT_FILE.gif)

Options

• -k, --keyframes N - Number of keyframes to extract (default: 10)
• -d, --keyframe-duration MS - Duration of each frame in milliseconds (default: 100, range: 1-30000)
• -i, --input-schedules N - Number of input schedules (default: 1)
• -t, --transition TYPE - Interpolation function for frame timing
  • Available: linear, sinoid, cubic, quadratic, exponential, bounce, elastic (default: linear)
• -s, --schedule TYPE - Algorithm to distribute keyframes across schedules
  • Available: uniform, front-load, back-load, center-peak, edge-peak, fibonacci, golden-ratio (default: uniform)
• -m, --magic TYPE - Apply magical effects to the GIF
  • Available: none, psychedelic, dither-bloom, edge-glow, temporal-blur, chromatic-shift, vaporwave (default: none)
• -v, --verbose - Enable verbose output

Examples

# Basic conversion with 15 keyframes
mime_mp4_gif.sh -k 15 video.mp4

# Fast animation with 50ms per frame
mime_mp4_gif.sh -k 20 -d 50 video.mp4

# Use sinusoidal transition with center-peak distribution
mime_mp4_gif.sh -t sinoid -s center-peak -k 20 video.mp4

# Apply psychedelic magic with fibonacci distribution
mime_mp4_gif.sh -m psychedelic -s fibonacci -k 13 video.mp4 trippy.gif

# Complex: 3 schedules with cubic interpolation and edge glow
mime_mp4_gif.sh -i 3 -t cubic -s front-load -m edge-glow -k 30 video.mp4

---

Installation

All scripts are available in this repository. Make sure they are executable:

chmod +x *.sh

Add them to your PATH for easy access:

export PATH="$PATH:/home/valknar/bin"

Or create symbolic links in /usr/local/bin:

sudo ln -s /home/valknar/bin/*.sh /usr/local/bin/

Common Dependencies

Most scripts require:

• bash (4.0+)
• bc - For floating-point arithmetic
• git - For repository operations (arty.sh)
• yq - For YAML parsing (arty.sh)
• jq - For JSON parsing

Additional dependencies are listed in each command's help output.

Contributing

Contributions are welcome! Please ensure:

• Scripts follow bash best practices
• Include comprehensive --help output with usage examples
• Test scripts before submitting

License

MIT License - See individual scripts for details.

---

Scripts collection maintained by valknar