Custom Bash Commands

Custom Bash Commands (CBC) is a Bash-based toolkit for Linux shells. It provides a small set of helper commands under cbc, a few standalone commands for opening project resources, and a curated alias catalog that is sourced at shell startup.

• Overview
• Key Components
• Prerequisites
• Installation
• Post-Installation Behavior
• Daily Usage
• Documentation Site
• Documentation Style
• Contribution Workflow
• Troubleshooting

Overview

The core script can use Charmbracelet gum for styled prompts and messages. The CBC_USE_GUM config key controls whether gum is auto-detected, required, or disabled. When sourced in an interactive shell, CBC loads config from ~/.config/cbc/cbc.config, sources installed module entrypoints from ~/.config/cbc/modules, and prints a version banner once per session (unless disabled). Manifest packages are installed or repaired only when users run cbc pkg load. It sources ~/.cbc_aliases.sh if present and warns when missing, then optionally sources ~/.bash_aliases when enabled in config.

Key Components

Path	Purpose
custom_bash_commands.sh	Main entry point. Defines cbc subcommands, styled output helpers, update checks, and module management.
cbc_aliases.sh	Alias catalog loaded by the main script.
install_cbc.sh	Installer that validates the repository path, copies scripts into ~, appends a sourcing line to .bashrc when missing, and creates common directories under ~/Documents.
docs/	Reference documentation for dependencies, SOPs, and commands.
zensical.toml	Zensical configuration for the documentation site.
requirements-docs.txt	Pinned Python package list for documentation builds.
CHANGELOG.md & cbc_logo_00001.png	Release history file and branding asset used in documentation.

Prerequisites

CBC expects the tools listed in docs/dependencies.md. Highlights include:

• gum for styled UI output (strongly recommended, optional).
• git and curl for update checks and module management.
• fzf, eza, and bat/batcat for aliases and formatted output.
• nvim for editor shortcuts.
• wl-copy for clipboard options in readme, wiki, changes, and releases.
• imv-x11 for the imv alias and man for fman.
• Python 3.10 or newer for Zensical documentation builds.

Installation

1. Ensure the canonical repository location exists:

   mkdir -p ~/Documents/github_repositories

2. Clone the project into the expected folder:

   git clone https://github.com/iop098321qwe/custom_bash_commands \
     ~/Documents/github_repositories/custom_bash_commands

3. Run the installer from inside the repository:

   cd ~/Documents/github_repositories/custom_bash_commands
   ./install_cbc.sh

   The script verifies the repository path, copies the main script and alias catalog into the home directory, appends the sourcing line to .bashrc when missing, and creates common directories under ~/Documents/Temporary and ~/Documents/github_repositories.

If you install manually, copy custom_bash_commands.sh and cbc_aliases.sh to ~ (prefixed with dots), mark them executable, and append the following to the end of ~/.bashrc:

source ~/.custom_bash_commands.sh

Restart the shell (or run refresh) when you finish so the new commands load.

Post-Installation Behavior

When the terminal sources CBC:

• Config is loaded from ~/.config/cbc/cbc.config when present.
• A version banner prints once per interactive session when CBC_SHOW_BANNER=true.
• Installed module entrypoints in ~/.config/cbc/modules are sourced when present.
• Packages listed in ~/.config/cbc/packages.toml are not aligned during startup. Run cbc pkg load to install or repair manifest modules.
• ~/.cbc_aliases.sh is sourced if it exists; missing files trigger a warning. When CBC_SOURCE_BASH_ALIASES=true (default), ~/.bash_aliases is sourced afterward.
• CBC_USE_GUM=auto (default) uses gum when installed and plain text otherwise.
• CBC_USE_GUM=true requires gum and blocks command execution when gum is missing.
• CBC_USE_GUM=false always uses plain text output.
• When gum is active, styled output follows Omarchy theme colors on Omarchy systems and falls back to the built-in Catppuccin-Mocha palette elsewhere.
• CBC does not check for updates automatically; use cbc update check.

Daily Usage

Discover and monitor CBC

• display_version (alias dv) prints the version banner.
• cbc doctor runs diagnostics for dependencies, config, modules, and GitHub update access.
• cbc doctor startup profiles CBC startup timing and prints hints for reducing terminal initialization delay.
• readme, wiki, changes, releases, and dotfiles open project resources in the default browser. Use -c to copy URLs where supported.
• cbc list [-v] lists available functions and aliases; it uses bat or batcat for formatted output when available.

Update CBC

• cbc update check queries the latest GitHub release.
• cbc update (alias ucbc) pulls the latest scripts via sparse checkout and reloads CBC.
• cbc test reloads CBC from the current custom_bash_commands repository root for development. It fails when run from another directory.

Configure CBC

• cbc config [-f] writes ~/.config/cbc/cbc.config with defaults.
• cbc config edit [--reset] opens the config in your editor, writing defaults when missing or when --reset is used.
• cbc config -e [--reset] is shorthand for the edit workflow.
• Config keys include CBC_SHOW_BANNER, CBC_BANNER_MODE, CBC_SOURCE_BASH_ALIASES, CBC_LIST_SHOW_DESCRIPTIONS, and CBC_USE_GUM.

Manage CBC modules

• cbc pkg stores module metadata in ~/.config/cbc/packages.toml.
• cbc pkg install <creator/repo|git-url|path> records a module source.
• cbc pkg load installs missing manifest modules, refreshes metadata, and sources entrypoints.
• cbc pkg update fast-forwards installed module repos, refreshes the manifest, and shows the previous and new installed versions in a table.
• cbc pkg uninstall <creator/repo|module-name> removes the manifest entry and local module folder.
• cbc pkg list shows installed module versions, status, and last update dates in a table.
• Subcommands support -h for help (for example, cbc pkg install -h).

Aliases and navigation

• Editor and shell helpers: editbash, refresh, fman, please, myip, imv.
• eza wrappers for directory listings such as la, ll, and lt.
• Python and editor shortcuts: py, python, vim, v.
• Single-letter aliases are limited to c, s, v, x, and z.
• On Ubuntu-like systems, bat is aliased to batcat.
• Use cbc list -v to see the full alias catalog.

Documentation Site

The documentation site uses Zensical with source files in docs/ and output in site/. Install the docs dependencies in a virtual environment before serving or building the site locally:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-docs.txt

Preview the site locally:

zensical serve

Build the static site:

zensical build --clean

GitHub Pages deployment is handled by .github/workflows/docs.yml when changes are pushed to main or when the workflow is run manually.

Documentation Style

Most Markdown in this project is wrapped at 80 characters. The following cases may exceed that limit when readability would otherwise suffer:

• Tables that depend on single-line rows.
• URLs that become ambiguous or unusable when broken across lines.
• Code fences where formatting depends on preserving longer lines.

Contribution Workflow

• Follow docs/operations/standard_operating_procedures.md when adding functions or aliases.
• Keep cbc list arrays in sync (function_names, function_descs, alias_names, alias_descs).
• Update documentation whenever behavior or dependencies change.
• Run zensical build --clean after changing documentation site files.

Troubleshooting

• Provisioning fails with a path error: install_cbc.sh verifies the repository lives at ~/Documents/github_repositories/custom_bash_commands and aborts if it does not. Move the clone into the expected location and rerun the script.
• Dependencies missing or failing silently: Compare your environment against docs/dependencies.md and confirm helpers such as gum, fzf, wl-copy, eza, nvim, and imv-x11 are installed.
• Gum required but missing: If CBC_USE_GUM=true, install gum or set CBC_USE_GUM=auto or CBC_USE_GUM=false in ~/.config/cbc/cbc.config.
• Manifest modules missing after startup: run cbc pkg load to install packages listed in ~/.config/cbc/packages.toml and source their entrypoints in the current shell.
• Terminal startup feels slow: run cbc doctor startup to measure CBC source time, module loading, banner rendering, and related settings.
• Zensical command missing: activate .venv or run .venv/bin/zensical build --clean after installing requirements-docs.txt.