Reference

Complete command reference, examples, tutorials, and additional resources.

Reference

📖 Complete Command Reference

Core Chief Commands

# Get comprehensive help system
chief.help                    # Full help with categories
chief.help commands           # Core commands only
chief.help plugins            # Plugin management  
chief.help config             # Configuration options
chief.help --compact          # Quick reference
chief.help --search git       # Search for git commands

# Quick tips and workflow hints
chief.hints                   # Compact tips
chief.hints --banner          # Tips with banner

# Explore all commands
chief.[tab][tab]

# Get help for any command
chief.update -?

# Find where any function/alias is defined
chief.whereis my_function

# Edit and auto-reload your bashrc
chief.bashrc

# Edit and auto-reload your bash_profile
chief.bash_profile

# Create/edit plugins instantly
chief.plugin mytools

# Set a shorter alias for Chief commands
# In chief.config: CHIEF_CFG_ALIAS="cf"
# Now use: cf.config, cf.plugin, etc.

Configuration Commands

# View current configuration
chief.config_show

# Set configuration values
chief.config_set PROMPT true
chief.config_set EDITOR "vim"

# Interactive configuration editor
chief.config

# Update config with new features (after upgrade)
chief.config_update
chief.config_update --dry-run

# Reload Chief after changes
chief.reload

Plugin Management

# Create/edit plugins
chief.plugin mytools          # Create or edit 'mytools' plugin
chief.plugin list             # List all available plugins

# Plugin discovery
chief.whereis function_name   # Find where function is defined
chief.help plugins            # Show plugin-provided commands

# Plugin management
chief.plugins_update          # Update remote plugins (if configured)
chief.plugins_root             # Navigate to plugins directory

System Management

# Update Chief
chief.update

# Check for updates
chief.update --check

# Version information
chief.version

# Uninstall Chief
chief.uninstall

🔧 Built-in Plugin Command Reference

SSL/TLS Certificate Management

# Certificate Authority Operations
chief.ssl_create-ca [ca_name] [options]
  Options:
    -c, --country CODE      Country code (default: US)
    -s, --state STATE       State/province (default: CA)
    -l, --city CITY         City/locality (default: San Francisco)
    -o, --org NAME          Organization name (default: ${ca_name} CA)
    -u, --unit NAME         Organizational unit (default: Certificate Authority)
    -e, --email EMAIL       Email address (optional)
    -d, --days DAYS         Validity period in days (default: 3650)
    -k, --keysize SIZE      Key size in bits (default: 4096)
    -f, --force             Force overwrite existing files

# TLS Certificate Creation
chief.ssl_create-tls-cert <cert_name> [ca_name] [options]
  Options:
    -c, --country CODE      Country code (inherit from CA if not specified)
    -s, --state STATE       State/province (inherit from CA)
    -l, --city CITY         City/locality (inherit from CA)
    -o, --org NAME          Organization name (inherit from CA)
    -u, --unit NAME         Organizational unit (default: IT Department)
    -e, --email EMAIL       Email address (optional)
    --san DOMAINS           Subject Alternative Names (comma-separated)
    --ip IPS                IP addresses for SAN (comma-separated)
    -d, --days DAYS         Validity period in days (default: 365)
    -k, --keysize SIZE      Key size in bits (default: 2048)
    -t, --type TYPE         Certificate type: server, client, email (default: server)
    -f, --force             Force overwrite existing files

# Certificate Analysis
chief.ssl_view-cert [options] <certificate_file>
  Options:
    -s, --subject           Show only certificate subject information
    -i, --issuer            Show only certificate issuer information
    -d, --dates             Show only validity dates
    -c, --chain             Show certificate chain if available
    -r, --raw               Show raw certificate text without parsing

# Certificate Download
chief.ssl_get-cert [options] <hostname> [port] [output_file]
  Options:
    -c, --chain             Download full certificate chain
    -r, --raw               Save raw certificate without text analysis
    -t, --timeout SECONDS  Connection timeout (default: 10)
    -v, --verify            Verify certificate chain
    -i, --info              Display certificate info after download

System Administration Tools

# File Permission Management
chief.etc_chmod-f <permissions> [directory]
  Options:
    -v, --verbose           Show each file being processed
    -n, --dry-run          Show what would be changed without making changes
    
chief.etc_chmod-d <permissions> [directory]
  Options:
    -v, --verbose           Show each directory being processed
    -n, --dry-run          Show what would be changed without making changes

# Dotfiles Management
chief.etc_copy_dotfiles <source_directory> <destination_directory> [options]
  Options:
    -v, --verbose           Show each file being copied
    -n, --dry-run          Show what would be copied without making changes
    -f, --force            Overwrite existing files without confirmation
    -b, --backup           Create backups of existing files (.bak extension)

# Bootable Media Creation
chief.etc_create_bootusb <iso_file> <disk_number> [options]
  Options:
    -f, --force             Skip confirmations (use with extreme caution)
    -k, --keep              Keep temporary conversion file

# Network and Storage
chief.etc_mount_share <share_path> <mount_path> <username>

# Scheduling and Automation
chief.etc_at_run <time> <command>
chief.etc_broadcast <message>

# Terminal Collaboration
chief.etc_shared-term_create <session_name>
chief.etc_shared-term_connect <session_name>

# Utilities
chief.etc_create_cipher [file_path] [--force]
chief.etc_folder_diff <folder1> <folder2>
chief.etc_isvalid_ip <ip_address>
chief.etc_ask_yes_or_no <message>
chief.etc_prompt <prompt_message>
chief.type_writer <message> [delay_seconds]
chief.etc_spinner <message> <command> <output_variable>

OpenShift Container Platform Management

# Cluster Authentication
chief.oc_login <cluster_name> [options]
  Options:
    -kc                     Use kubeconfig authentication
    -ka                     Use kubeadmin authentication
    -i                      Skip TLS verification (insecure)

# Certificate Management
chief.oc_approve_csrs [options]
  Options:
    -a, --all               Approve all pending CSRs without confirmation
    -l, --list              List pending CSRs without approving
    -f, --filter PATTERN   Only approve CSRs matching pattern
    -n, --dry-run          Show what would be approved without making changes

# Resource Management
chief.oc_show_stuck_resources <namespace> [options]
  Options:
    --fix                   Automatically remove finalizers from terminating resources
    --dry-run              Show what would be fixed without making changes

# Namespace Management
chief.oc_delete_stuck_ns <namespace> [options]
  Options:
    --dry-run              Show what would be done without making changes
    --no-confirm           Skip confirmation prompts (dangerous)

📖 Installation Methods

Method 1: Quick Install (Recommended)

bash -c "$(curl -fsSL https://raw.githubusercontent.com/randyoyarzabal/chief/refs/heads/main/tools/install.sh)"

Note: This installation only affects your Bash environment. Your current shell (Zsh, Fish, etc.) and any custom configurations remain completely untouched.

Method 2: Manual Install

# 1. Clone the repository
git clone --depth=1 https://github.com/randyoyarzabal/chief.git ~/.chief

# 2. Copy configuration template
cp ~/.chief/templates/chief_config_template.sh ~/.chief_config.sh

# 3. Add to shell config file
echo 'export CHIEF_CONFIG="$HOME/.chief_config.sh"' >> ~/.bash_profile
echo 'export CHIEF_PATH="$HOME/.chief"' >> ~/.bash_profile
echo 'source ${CHIEF_PATH}/chief.sh' >> ~/.bash_profile

# 4. Restart terminal

Method 3: Library-Only Usage

# Use Chief's functions without full setup
source ~/.chief/chief.sh --lib-only

📖 Advanced Examples & Tutorials

Example 1: DevOps Plugin

# Create a DevOps plugin
chief.plugin devops

# Add functions like:
function devops.docker_cleanup() {
    docker system prune -f
    docker volume prune -f
}

function devops.k8s_pods() {
    kubectl get pods --all-namespaces
}

function devops.deploy() {
    local environment="${1:-staging}"
    echo "Deploying to $environment..."
    
    case "$environment" in
        staging)
            kubectl apply -f k8s/staging/
            ;;
        production)
            if chief.etc_confirm "Deploy to PRODUCTION?"; then
                kubectl apply -f k8s/production/
            fi
            ;;
        *)
            echo "Unknown environment: $environment"
            return 1
            ;;
    esac
}

Example 2: Project Management Plugin

# Create project-specific plugin
chief.plugin myapp

function myapp.setup() {
    cd ~/projects/myapp
    npm install
    docker-compose up -d
}

function myapp.deploy() {
    cd ~/projects/myapp
    ./deploy.sh production
}

function myapp.logs() {
    tail -f ~/projects/myapp/logs/app.log
}

function myapp.test() {
    cd ~/projects/myapp
    npm test
}

Example 3: Git Workflow Plugin

# Create git workflow plugin
chief.plugin gitflow

function gitflow.feature_start() {
    local feature_name="$1"
    if [[ -z "$feature_name" ]]; then
        echo "Usage: gitflow.feature_start <feature-name>"
        return 1
    fi
    
    git checkout develop
    git pull origin develop
    git checkout -b "feature/${feature_name}"
    echo "Started feature: ${feature_name}"
}

function gitflow.feature_finish() {
    local current_branch=$(git branch --show-current)
    
    if [[ ! "$current_branch" =~ ^feature/ ]]; then
        echo "Not on a feature branch"
        return 1
    fi
    
    git checkout develop
    git merge "${current_branch}"
    git branch -d "${current_branch}"
    echo "Finished feature: ${current_branch}"
}

function gitflow.hotfix() {
    local version="$1"
    if [[ -z "$version" ]]; then
        echo "Usage: gitflow.hotfix <version>"
        return 1
    fi
    
    git checkout main
    git pull origin main
    git checkout -b "hotfix/${version}"
    echo "Started hotfix: ${version}"
}

Example 4: Team Collaboration Plugin

# Create team plugin with shared utilities
chief.plugin team

function team.standup() {
    echo "📅 Daily Standup - $(date)"
    echo "🎯 Yesterday:"
    git log --oneline --since="yesterday" --author="$(git config user.email)"
    echo ""
    echo "🚀 Today's Plan:"
    echo "  • Check JIRA tickets"
    echo "  • Review PRs"
    echo "  • Continue feature development"
}

function team.pr_review() {
    local pr_number="$1"
    if [[ -z "$pr_number" ]]; then
        echo "Usage: team.pr_review <pr-number>"
        return 1
    fi
    
    gh pr checkout "$pr_number"
    git log --oneline main..HEAD
    echo "Ready to review PR #${pr_number}"
}

function team.deploy_status() {
    echo "🚀 Deployment Status:"
    echo "Staging: $(curl -s https://staging.myapp.com/health | jq -r .status)"
    echo "Production: $(curl -s https://myapp.com/health | jq -r .status)"
}

🛟 Comprehensive Troubleshooting

Installation Issues

Q: Chief commands not found after installation

# Solution: Restart terminal or source config file
source ~/.bash_profile

# Check if Chief is loaded
echo $CHIEF_PATH
chief.help

Q: “Bad substitution” or “Syntax error” messages

# Check bash version - Chief requires Bash 4.0+
bash --version

# If using older bash (like macOS default), upgrade:
# macOS: brew install bash
# Linux: Update your package manager

# Ensure you're running bash
echo $SHELL
bash  # Switch to bash if needed

Q: Permission denied during installation

# Ensure write access to home directory
ls -la ~ | grep chief

# Fix permissions if needed
chmod 755 ~/.chief
chmod 644 ~/.chief_config.sh

Configuration Issues

Q: Configuration changes not taking effect

# Reload Chief
chief.reload

# Check configuration syntax
bash -n ~/.chief_config.sh

# View current configuration
chief.config_show

Q: Vault functions not working

# Check if ansible is installed (optional dependency)
ansible-vault --version

# Install if needed:
# macOS: brew install ansible
# Linux: pip3 install ansible-core
# Windows: pip install ansible-core

# Check vault file permissions
ls -la ~/.chief_vault*

Q: OpenShift functions not working

# Check if OpenShift CLI is installed (optional dependency)
oc version --client

# Install if needed:
# macOS: brew install openshift-cli
# Linux: Download from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/
# Windows: Download from Red Hat or use package manager

# Verify oc is in PATH
which oc

Plugin Issues

Q: Plugins not loading

# Check plugin directory and file naming
ls ~/chief_plugins/*_chief-plugin.sh

# Verify plugin syntax
bash -n ~/chief_plugins/myplugin_chief-plugin.sh

# Check plugin path configuration
chief.config_show | grep PLUGINS_PATH

# Reload plugins
chief.reload

Q: Remote plugin sync not working

# Check Git configuration
cd "$CHIEF_CFG_PLUGINS_PATH"
git status
git remote -v

# Force update
chief.plugins_update --force

# Reset repository
rm -rf "$CHIEF_CFG_PLUGINS_PATH"
chief.reload  # Will re-clone

Q: SSH keys not auto-loading

# Verify key naming (must end in .key) and path
ls ~/.ssh/*.key

# Check configuration
chief.config_show | grep SSH_KEYS_PATH

# Manually load keys
ssh-add ~/.ssh/id_rsa

Built-in Plugin Issues

Q: SSL plugin functions not working

# Check if OpenSSL is installed
openssl version

# Install OpenSSL if missing:
# macOS: brew install openssl
# Linux: Use your package manager (apt install openssl, yum install openssl, etc.)

# Verify SSL functions are available
chief.whereis chief.ssl_create-ca

# Test with help option
chief.ssl_create-ca -?

Q: ETC plugin permission functions fail

# Check if you have permission to modify files/directories
ls -la /path/to/target

# For system directories, use sudo:
sudo chief.etc_chmod-f 644 /system/path

# Verify target directory exists
ls -d /path/to/directory

# Use dry-run to preview changes
chief.etc_chmod-f -n 644 /path

Q: OpenShift functions not working

# Check if OpenShift CLI is installed
oc version --client

# Install if needed:
# macOS: brew install openshift-cli
# Linux: Download from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/
# Windows: Download from Red Hat or use package manager

# Verify oc is in PATH
which oc

# Check if logged into cluster
oc whoami

# Login to cluster first
oc login https://api.cluster.example.com:6443

Q: Vault integration not working for OpenShift

# Check Vault CLI is installed
vault version

# Verify environment variables are set
echo $VAULT_ADDR
echo $VAULT_TOKEN
echo $CHIEF_VAULT_OC_PATH

# Test Vault connectivity
vault auth -method=token

# Check if cluster secret exists in Vault
vault kv get secrets/openshift/cluster-name

# Verify secret contains required fields
vault kv get -format=json secrets/openshift/cluster-name | jq '.data'

Q: Bootable USB creation fails

# macOS troubleshooting
diskutil list  # Verify disk number
sudo diskutil unmountDisk /dev/diskN  # Unmount first if needed

# Linux troubleshooting  
lsblk  # Verify disk device
sudo umount /dev/sdX*  # Unmount all partitions

# Check ISO file integrity
file your-image.iso
md5sum your-image.iso  # Compare with known hash

# Verify sufficient privileges
sudo -v  # Test sudo access

# Check if CIFS utilities are installed
mount.cifs --help

# Install if needed:
# Ubuntu/Debian: sudo apt install cifs-utils
# CentOS/RHEL: sudo yum install cifs-utils

# Test network connectivity
ping server-name-or-ip
telnet server-ip 445  # Test SMB port

# Check mount point exists
sudo mkdir -p /mnt/share

# Manual mount with debugging
sudo mount -t cifs -v //server/share /mnt/share -o username=user

Performance Issues

Q: Chief loading slowly

# Disable non-essential features
chief.config_set banner false
chief.config_set hints false
chief.config_set autocheck_updates false

# Check for large plugin files
find ~/chief_plugins -name "*.sh" -size +1M

# Enable debug mode to identify bottlenecks
export CHIEF_DEBUG=1
source ~/.bash_profile

Advanced Debugging

Enable Debug Mode

# Enable debug output
export CHIEF_DEBUG=1
source ~/.bash_profile

# This shows detailed loading information

Check Dependencies

# Verify all requirements
bash --version     # Should be 4.0+
git --version      # Should be 2.0+
ansible-vault --version 2>/dev/null || echo "Ansible not installed (optional)"
oc version --client 2>/dev/null || echo "OpenShift CLI not installed (optional)"

Reset Chief Completely

# Backup configuration
cp ~/.chief_config.sh ~/.chief_config.sh.backup

# Remove Chief
chief.uninstall

# Clean install
bash -c "$(curl -fsSL https://raw.githubusercontent.com/randyoyarzabal/chief/refs/heads/main/tools/install.sh)"

# Restore configuration
cp ~/.chief_config.sh.backup ~/.chief_config.sh
chief.reload

🤖 Contributing

We welcome contributions! Here’s how to get involved:

Getting Started

Fork the repository on GitHub
Clone your fork locally
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone git@github.com:yourusername/chief.git
cd chief

# Install in development mode
./tools/install.sh

# Make changes and test
chief.reload

# Run tests (if available)
bash tests/run_tests.sh

Contribution Guidelines

Code Style: Follow existing bash scripting conventions
Documentation: Update docs for new features
Testing: Test on multiple bash versions and platforms
Commits: Use clear, descriptive commit messages
Pull Requests: Include description of changes and testing done

Areas for Contribution

New Plugins: Create useful plugins for common workflows
Bug Fixes: Fix issues and improve stability
Documentation: Improve guides and examples
Testing: Add test coverage and CI/CD improvements
Performance: Optimize loading times and memory usage

Development Resources

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

License Summary

✅ Commercial use
✅ Modification
✅ Distribution
✅ Private use
❌ Liability
❌ Warranty

🙏 Acknowledgments

Git Project - Git completion and prompt scripts
Bash Community - Inspiration from various Bash framework projects
Contributors - Everyone who has contributed to Chief’s development
Users - Feedback and bug reports that make Chief better

Special Thanks

Built with ❤️ for the terminal-loving community
Inspired by the need for clean, organized shell environments
Designed to enhance productivity without breaking existing setups

🔗 External Resources

Official Links

GitHub Repository - Source code and issue tracking
Latest Release - Download latest version
Issues - Bug reports and feature requests
Discussions - Community discussions

Documentation

Version Management - Technical version information
Plugin Template - Starting point for new plugins
Configuration Template - Default configuration

Community Resources

Bash Learning: Bash Guide for Beginners
Advanced Bash: Advanced Bash-Scripting Guide
Shell Scripting: ShellCheck for script analysis

Need help? Each page has detailed guides and examples. Still stuck? Check our troubleshooting section or open an issue.

← Back to Home

Reference

Table of contents

📖 Complete Command Reference

Core Chief Commands

Configuration Commands

Plugin Management

System Management

🔧 Built-in Plugin Command Reference

SSL/TLS Certificate Management

System Administration Tools

OpenShift Container Platform Management

📖 Installation Methods

Method 1: Quick Install (Recommended)

Method 2: Manual Install

Method 3: Library-Only Usage

📖 Advanced Examples & Tutorials

Example 1: DevOps Plugin

Example 2: Project Management Plugin

Example 3: Git Workflow Plugin

Example 4: Team Collaboration Plugin

🛟 Comprehensive Troubleshooting

Installation Issues

Q: Chief commands not found after installation

Q: “Bad substitution” or “Syntax error” messages

Q: Permission denied during installation

Configuration Issues

Q: Configuration changes not taking effect

Q: Vault functions not working

Q: OpenShift functions not working

Plugin Issues

Q: Plugins not loading

Q: Remote plugin sync not working

Q: SSH keys not auto-loading

Built-in Plugin Issues

Q: SSL plugin functions not working

Q: ETC plugin permission functions fail

Q: OpenShift functions not working

Q: Vault integration not working for OpenShift

Q: Bootable USB creation fails

Q: Network share mounting fails

Performance Issues

Q: Chief loading slowly

Advanced Debugging

Enable Debug Mode

Check Dependencies

Reset Chief Completely

🤖 Contributing

Getting Started

Development Setup

Contribution Guidelines

Areas for Contribution

Development Resources

📄 License

License Summary

🙏 Acknowledgments

Special Thanks

🔗 External Resources

Official Links

Documentation

Community Resources