CLI Helper

The customrc-cli.sh helper provides a git-style command-line interface for managing the CustomRC shell configuration system.

Location

helpers/customrc-cli.sh

Overview

This helper adds the customrc command to your shell, providing subcommands for managing modules, caches, debug mode, and syncing configurations across machines. Unlike other helpers that are unset after initialization, CLI functions remain available for interactive use.

Commands

`customrc help`

Displays help information for all commands or a specific command.

customrc help [command]

Usage:

# Show all commands
customrc help

# Show help for a specific command
customrc help sync
customrc help modules
customrc help cache
customrc help complete

`customrc version`

Shows the current CustomRC version.

customrc version

Example Output:

customrc 1.0.0

`customrc status`

Displays an overall status summary of the CustomRC installation.

customrc status

Example Output:

━━━━[CustomRC Status]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Version:     1.0.0
  Path:        /Users/you/.customrc
  Modules:     /Users/you/.customrc/rc-modules
  Cache:       /Users/you/.cache/customrc
  Debug:       disabled
  Sync:        git (branch: main, 0 uncommitted)
  Modules:     Global: 12, Darwin: 5, Linux: 0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

`customrc doctor`

Runs health checks to identify configuration issues.

customrc doctor

Checks performed:

Check	Description
CustomRC directory	Verifies `CUSTOMRC_PATH` exists
rc-modules directory	Verifies modules directory exists
Required helpers	Checks for `cache.sh` and `monolithic.sh`
Module syntax	Validates all `.sh` files with `bash -n`
Cache directory	Verifies cache directory is writable
configs.sh	Confirms configuration file exists
Updates	Checks if updates are available from remote (non-blocking)

Example Output:

━━━━[CustomRC Doctor]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[✓] CustomRC directory exists: /Users/you/.customrc
[✓] rc-modules directory exists
[✓] Helper found: cache.sh
[✓] Helper found: monolithic.sh

[i] Checking module syntax...
[✓] All modules have valid syntax

[✓] Cache directory is writable
[✓] configs.sh exists

[i] Checking for updates...
[✓] CustomRC is up to date

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[✓] All checks passed!

Update Check Notes:

The update check fetches from the remote repository and reports if updates are available
If updates are found, a warning is shown: N update(s) available (run: customrc update)
If no git remote is configured or it's not a git repository, a warning is shown but does not count as an error
Network issues during the update check are reported as warnings, not errors

Sync Commands

Manage git synchronization of your rc-modules directory.

`customrc sync init`

Initializes rc-modules as a git repository or clones from a URL.

customrc sync init [url]

Usage:

# Initialize as new git repo
customrc sync init

# Clone from remote URL (backs up existing rc-modules first)
customrc sync init https://github.com/you/my-shell-config.git

`customrc sync push`

Pushes rc-modules changes to the remote repository.

customrc sync push

`customrc sync pull`

Pulls latest rc-modules from the remote repository.

customrc sync pull

`customrc sync status`

Shows git status of the rc-modules directory.

customrc sync status

Cache Commands

Manage the monolithic cache and tool caches.

`customrc cache status`

Displays cache status including size, age, and line count.

customrc cache status

Example Output:

Cache Status:

  Monolithic cache:
    Path:    /Users/you/.cache/customrc/monolithic.sh
    Size:    20 KB
    Lines:   627
    Created: 2 hours ago

`customrc cache clear`

Clears all caches or a specific cache.

customrc cache clear [name]

Usage:

# Clear all caches
customrc cache clear

# Clear specific cache
customrc cache clear starship

`customrc cache rebuild`

Forces regeneration of the monolithic cache.

customrc cache rebuild

This clears the existing monolithic cache and regenerates it by re-sourcing all modules.

Modules Commands

Manage shell configuration modules.

`customrc modules list`

Lists all modules with their load status.

customrc modules list

Example Output:

Modules:

  Global/
    ✓ aliases.sh
    ✓ functions.sh
    ✓ fzf.sh
    ✗ nvm.sh (ignored)

  Darwin/
    ✓ brew.sh
    ✗ iterm.sh (ignored)

`customrc modules edit`

Opens a module in your editor.

customrc modules edit <name>

Usage:

# Edit by filename (searches all directories)
customrc modules edit docker.sh
customrc modules edit docker  # .sh extension is optional

The command searches Global/, Darwin/, and Linux/ directories for the module.

`customrc modules new`

Creates a new module from a template.

customrc modules new <category/name>
customrc modules new <name>  # defaults to Global/

Usage:

# Create in Global directory
customrc modules new my-aliases

# Create in specific category
customrc modules new Darwin/macos-utils
customrc modules new Linux/linux-tools

Template generated:

# my-aliases
# CustomRC module - Global
# Created: 2024-01-15

# Add your aliases, functions, and configurations below

The module opens in your $EDITOR after creation.

Debug Commands

Toggle debug mode for troubleshooting.

`customrc debug status`

Shows current debug mode status.

customrc debug status

`customrc debug on`

Enables debug mode in configs.sh.

customrc debug on

After enabling, restart your shell to see verbose output with timing information.

`customrc debug off`

Disables debug mode in configs.sh.

customrc debug off

Update Command

Update CustomRC to the latest version from the remote repository.

`customrc update`

Fetches and pulls the latest changes from the remote repository.

customrc update

Behavior:

Checks if CustomRC directory is a git repository
Warns and exits if there are uncommitted changes
Fetches from the remote and shows new commits
Pulls the updates
Automatically rebuilds the monolithic cache
Reminds you to restart your shell

`customrc update --force`

Forces the update even with uncommitted changes. Uses git reset --hard instead of git pull.

customrc update --force

Warning: This will discard any local uncommitted changes in the CustomRC directory.

Example Output:

━━━━[CustomRC Update]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[i] Fetching from origin/main...
[i] Found 3 new commit(s)

89b682a feat: add platform detection and improve module command help messages
fecc4ed feat: add update command for CustomRC to fetch and pull latest changes
a96413a feat: enhance user guide with CLI commands for module management

[i] Pulling updates...
[✓] Updated CustomRC to latest version

[i] Rebuilding cache...
[i] Clearing monolithic cache...
[i] Rebuilding monolithic cache...
[✓] Rebuilt monolithic cache

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[✓] Update complete!
[i] Restart your shell to apply changes

Notes:

If CustomRC is not a git repository, the command will fail with guidance
If no remote is configured, you'll be prompted to add one
If already up to date, the command exits early without rebuilding cache

Internal Functions

These functions are used internally by the CLI:

Function	Purpose
`_customrc_info`	Prints info message with `[i]` prefix
`_customrc_success`	Prints success message with `[✓]` prefix
`_customrc_warn`	Prints warning message with `[!]` prefix
`_customrc_error`	Prints error message with `[✗]` prefix
`_customrc_get_path`	Returns CustomRC installation path
`_customrc_get_modules_path`	Returns rc-modules directory path
`_customrc_get_helpers_path`	Returns helpers directory path
`_customrc_get_cache_path`	Returns cache directory path

Complete Commands

Manage shell tab completions for the customrc CLI.

`customrc complete install`

Installs shell completions for your detected shell (Bash or Zsh).

customrc complete install

Behavior:

Auto-detects your shell (Bash or Zsh)
Installs the appropriate completion script to your shell's completion directory
Creates the completion directory if it does not exist

Completion directories:

Shell	Directory (in order of preference)
Bash	`~/.bash_completion.d/` (user-local, preferred)
Bash	`/usr/local/etc/bash_completion.d/` (if writable)
Bash	`/etc/bash_completion.d/` (if writable)
Zsh	`~/.oh-my-zsh/custom/completions/` (if Oh My Zsh is installed)
Zsh	`~/.zsh/completions/` (user-local, preferred)
Zsh	`/usr/local/share/zsh/site-functions/` (if writable)
Zsh	`/usr/share/zsh/site-functions/` (if writable)

User-local directories are preferred to avoid requiring sudo on macOS and other systems where system directories are protected.

Example Output:

[✓] Installed zsh completions to: /Users/you/.zsh/completions/_customrc
[i] Restart your shell or source your rc file to activate completions

After installing:

# Completions work immediately after restarting your shell
exec $SHELL

# Then you can use tab completion
customrc syn<TAB>      # completes to "sync"
customrc sync <TAB>    # shows: init push pull status

`customrc complete status`

Shows whether completions are installed and for which shell.

customrc complete status

Example Output:

Completion Status:

  Detected shell: zsh
  Completion dir: /Users/you/.zsh/completions
  Status: ✓ Installed
  Location: /Users/you/.zsh/completions/_customrc

Or when not installed:

Completion Status:

  Detected shell: bash
  Completion dir: /etc/bash_completion.d
  Status: ! Not installed

`customrc complete uninstall`

Removes the completion script for your current shell.

customrc complete uninstall

Example Output:

[✓] Removed zsh completions from: /Users/you/.zsh/completions/_customrc

Auto-Prompt on First Use

When you open a new interactive shell and completions are not installed, CustomRC displays a one-time message:

[i] Shell completions are available for CustomRC
    Run `customrc complete install` to enable tab completion

This message appears only once per shell session. The check runs in the background to avoid delaying shell startup.

Completion Features

The completion scripts provide intelligent suggestions for:

Top-level commands: sync, cache, modules, debug, update, status, doctor, version, help, complete
Subcommands: Context-aware completion based on the command (e.g., customrc sync <TAB> suggests init push pull status)
Module names: When using customrc modules edit <TAB>, available modules are suggested with their categories

Examples:

# Complete commands
customrc sta<TAB>       # completes to "status"
customrc comp<TAB>      # completes to "complete"

# Complete subcommands
customrc cache <TAB>    # shows: clear rebuild status
customrc modules <TAB>  # shows: list edit new

# Complete module names
customrc modules edit <TAB>       # shows: Global/aliases Global/docker Darwin/brew

Examples

Setting Up Sync

# Initialize your rc-modules as a git repo
customrc sync init

# Add remote and push
cd ~/.customrc/rc-modules
git remote add origin https://github.com/you/my-shell-config.git
git add -A && git commit -m "Initial commit"
customrc sync push

On a New Machine

# After installing CustomRC, clone your modules
customrc sync init https://github.com/you/my-shell-config.git

Debugging Slow Startup

# Enable debug mode
customrc debug on

# Restart shell to see timing
exec $SHELL

# After identifying slow modules, disable debug
customrc debug off

Creating a New Module

# Create and edit a new module
customrc modules new Global/docker

# View all modules
customrc modules list

Enabling Tab Completions

# Check if completions are installed
customrc complete status

# Install completions for your shell
customrc complete install

# Restart shell to activate completions
exec $SHELL

# Now use tab completion
customrc mod<TAB>      # completes to "modules"
customrc modules <TAB> # shows: list edit new
customrc modules edit <TAB> # shows available modules

FilesExpand file tree

customrc-cli.md

Latest commit

History

customrc-cli.md

File metadata and controls

CLI Helper

Location

Overview

Commands

customrc help

customrc version

customrc status

customrc doctor

Sync Commands

customrc sync init

customrc sync push

customrc sync pull

customrc sync status

Cache Commands

customrc cache status

customrc cache clear

customrc cache rebuild

Modules Commands

customrc modules list

customrc modules edit

customrc modules new

Debug Commands

customrc debug status

customrc debug on

customrc debug off

Update Command

customrc update

customrc update --force

Internal Functions

Complete Commands

customrc complete install

customrc complete status

customrc complete uninstall

Auto-Prompt on First Use

Completion Features

Examples

Setting Up Sync

On a New Machine

Debugging Slow Startup

Creating a New Module

Enabling Tab Completions

See Also

`customrc help`

`customrc version`

`customrc status`

`customrc doctor`

`customrc sync init`

`customrc sync push`

`customrc sync pull`

`customrc sync status`

`customrc cache status`

`customrc cache clear`

`customrc cache rebuild`

`customrc modules list`

`customrc modules edit`

`customrc modules new`

`customrc debug status`

`customrc debug on`

`customrc debug off`

`customrc update`

`customrc update --force`

`customrc complete install`

`customrc complete status`

`customrc complete uninstall`