Chief

Transform your terminal experience with organized bash functions, aliases, and a powerful plugin system.

This project is maintained by randyoyarzabal

← Back to Home

Configuration

Advanced configuration options, multi-system setup, and team collaboration workflows.

Table of contents

  1. Configuration
    1. 🛠️ Configuration Management
      1. Basic Configuration Commands
    2. ⚙️ Configuration Options
      1. Core Settings
      2. Environment Variables
      3. Plugin Configuration
    3. 🌟 Advanced Features
      1. SSH Key Auto-loading
      2. Custom Prompt Features
      3. Personal Plugin Sync
    4. 🌐 Multi-System Setup
      1. 🎯 Primary Use Case: Single User, Multiple Systems
      2. Portable Setup Configuration
        1. 🚀 One-Time Setup (any new system)
        2. 🎯 Result
        3. 🔍 Daily Workflow
    5. 👥 Team Collaboration
      1. 📋 Two Setup Scenarios
    6. 🔄 Scenario A: Existing Repository
      1. 1. Add Plugins to Existing Repo
      2. 2. Team Member Configuration
      3. 3. Plugin File Discovery Rules
    7. 🆕 Scenario B: New Repository
      1. 1. Create New Team Plugins Repository
      2. 2. Team Member Setup
    8. 🔒 Vault Configuration
      1. Creating and Managing Vaults
      2. Team Vault Best Practices
    9. 🎯 Configuration Examples
      1. Developer Workstation
      2. Server/CI Environment
      3. Team Lead Setup
    10. 🔧 Troubleshooting Configuration
      1. Common Configuration Issues
      2. Plugin Sync Issues
    11. 🎯 Next Steps

🛠️ Configuration Management

Chief is highly customizable. Use chief.config to edit the config file or chief.config_set <option> <value> for direct command-line configuration.

Interactive Behavior: By default, chief.config_set prompts for confirmation before modifying your configuration file. Use --yes (or -y) to skip prompts for scripting.

Basic Configuration Commands

# Edit configuration file
chief.config

# Set configuration variables directly (use option name without CHIEF_CFG_ prefix)
chief.config_set banner false         # Sets CHIEF_CFG_BANNER=false (prompts for confirmation)
chief.config_set banner=false         # Same as above using key=value syntax
chief.config_set --yes prompt true    # Sets CHIEF_CFG_PROMPT=true (no prompt)  
chief.config_set colored_ls=true      # Sets CHIEF_CFG_COLORED_LS=true (prompts for confirmation)

# List all configuration variables and current values  
chief.config_set --list

# Update configuration with new template options (perfect for upgrades)
chief.config_update                   # Add missing options, handle renames, preserve customizations
chief.config_update --dry-run         # Preview changes without applying them

# Disable interactive prompts globally
chief.config_set config_set_interactive false

⚙️ Configuration Options

Core Settings

Configuration Default Description
CHIEF_CFG_BANNER true Show startup banner
CHIEF_CFG_HINTS true Display helpful tips on startup
CHIEF_CFG_PROMPT false Use Chief’s custom prompt (keep disabled if using Oh My Bash/Starship)
CHIEF_CFG_COLORED_PROMPT true Colorize the prompt
CHIEF_CFG_GIT_PROMPT true Git-aware prompt features
CHIEF_CFG_MULTILINE_PROMPT false Enable multiline prompt display
CHIEF_CFG_SHORT_PATH false Show only current directory name in prompt
CHIEF_CFG_COLORED_LS false Colorize ls command output
CHIEF_CFG_CONFIG_SET_INTERACTIVE true Prompt for confirmation in chief.config_set
CHIEF_CFG_CONFIG_UPDATE_BACKUP true Create backups during config updates (only when changes made)
CHIEF_CFG_PLUGINS_TYPE "local" Use "local" or "remote" plugins
CHIEF_CFG_SSH_KEYS_PATH unset Auto-load SSH keys from path
CHIEF_CFG_ALIAS unset Create short alias (e.g., "cf")
CHIEF_CFG_AUTOCHECK_UPDATES false Check for updates on startup
CHIEF_CFG_UPDATE_BRANCH "main" Branch to track for updates: any valid Git branch (⚠️ non-main may be unstable)

Environment Variables

These are environment variables (not configuration settings) that affect Chief’s behavior:

Variable Default Description
CHIEF_HOST unset Override hostname display in prompt. Useful for marking systems without changing hostname.

Example:

# Add to your ~/.bashrc or ~/.bash_profile
export CHIEF_HOST="production-server"

# Or set temporarily for current session
CHIEF_HOST="dev-box" bash

Plugin Configuration

Configuration Description
CHIEF_CFG_PLUGINS_GIT_REPO Remote Git repository URL for plugins
CHIEF_CFG_PLUGINS_GIT_BRANCH Git branch to use (default: “main”)
CHIEF_CFG_PLUGINS_PATH Local plugin directory (also remote repo clone location)
CHIEF_CFG_PLUGINS_GIT_PATH [Remote only] Relative path within repo containing plugins (empty = repo root)
CHIEF_CFG_PLUGINS_GIT_AUTOUPDATE Auto-update plugins on startup (with local changes protection)

🌟 Advanced Features

SSH Key Auto-loading

# In chief.config, set:
CHIEF_CFG_SSH_KEYS_PATH="$HOME/.ssh"

# Chief automatically loads all *.key files
# Supports RSA, ed25519, and other key types
# Use symlinks for selective loading (e.g., ln -s id_rsa mykey.key)

Custom Prompt Features

⚠️ Important: Only enable Chief’s prompt if you’re not using Oh My Bash, Starship, or other prompt customization tools. Chief’s prompt is disabled by default to prevent conflicts.

# Enable git-aware prompt (only if not using other prompt tools)
CHIEF_CFG_PROMPT=true
CHIEF_CFG_GIT_PROMPT=true

# Shows: user@host:~/project (main|+2-1) $ 
#        ↑              ↑     ↑    ↑  ↑
#        user           path  branch +staged -unstaged

Personal Plugin Sync

# Sync your personal plugins across machines
CHIEF_CFG_PLUGINS_TYPE="remote"
CHIEF_CFG_PLUGINS_GIT_REPO="git@github.com:yourusername/my-bash-plugins.git"

# Auto-update on startup
CHIEF_CFG_PLUGINS_GIT_AUTOUPDATE="true"

🌐 Multi-System Setup

🎯 Primary Use Case: Single User, Multiple Systems

Chief is primarily designed as a single-user system that follows you across multiple environments:

# Your personal setup works the same everywhere:
# Laptop:     chief.vault_file-load → access your secrets
# Server:     chief.vault_file-load → same secrets, same functions  
# CI/CD:      chief.vault_file-load → consistent automation

Portable Setup Configuration

Real-world example: Set up Chief with remote plugins and vault that follows you across all systems.

🚀 One-Time Setup (any new system)

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

# 2. Configure your plugin repository (replace with your repo)
chief.config_set -y PLUGINS_GIT_REPO="git@github.com:yourusername/my-plugins.git"
chief.config_set -y PLUGINS_PATH="${HOME}/chief_plugins"
chief.config_set -y PLUGINS_GIT_BRANCH="main"
chief.config_set -y PLUGINS_GIT_PATH="bash/plugins"   # or "" for repo root, this is plugins path relative to PLUGINS_PATH
chief.config_set -y PLUGINS_GIT_AUTOUPDATE="false"    # manual updates
chief.config_set -y PLUGINS_TYPE="remote"             # 🔑 Enable remote sync

# 3. (Optional) Enable multi-line prompt, useful when current working dir is deep.
chief.config_set -y MULTILINE_PROMPT=true 

# 4. (Optional) Load your encrypted secrets (if exists)
chief.vault_file-load  # Team vault (.chief_shared-vault - if exists)
chief.vault_file-load ~/.my-personal-vault     # Personal vault

📖 For detailed vault setup and management, see: Vault Configuration

🎯 Result

🔍 Daily Workflow

chief.plugins_update           # Get latest team plugins
chief.vault_file-load          # Load secrets when needed
chief.plugin mytools           # Edit/create plugins
chief.whereis my_function      # Find any function instantly

👥 Team Collaboration

The remote plugins feature enables powerful team collaboration:

Chief is designed with teams in mind. Share your bash functions, aliases, and tools across your entire team for consistent development environments.

🔑 Key Concept: Chief automatically loads any file ending with _chief-plugin.sh from your configured plugin directory. The prefix before _chief-plugin.sh becomes the plugin name (e.g., devops_chief-plugin.sh → plugin name “devops”). This makes it perfect for both existing repositories and new team setups, with easy plugin management via chief.plugin <name>.

📋 Two Setup Scenarios

Choose the approach that fits your team’s situation:

🔄 Scenario A: Existing Repository

Perfect when you already have a team repository and want to add Chief plugins alongside your existing code.

1. Add Plugins to Existing Repo

# Navigate to your existing team repository
cd ~/your-existing-team-repo

# Create plugins in any subdirectory (or repo root)
mkdir -p tools/bash-plugins  # or scripts/, devops/, etc.

# Create your first team plugin - MUST end with _chief-plugin.sh
# Plugin name will be "devops" (prefix before _chief-plugin.sh)
cat > tools/bash-plugins/devops_chief-plugin.sh << 'EOF'
#!/usr/bin/env bash
# Team DevOps Tools - loaded automatically by Chief

# Prevent direct execution
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  echo "Error: $(basename "${BASH_SOURCE[0]}") must be sourced, not executed."
  exit 1
fi

echo "Team DevOps plugin loaded"

function devops.deploy() {
    echo "🚀 Deploying with team standards..."
    # Your existing deployment scripts/logic
    ./scripts/deploy.sh "$@"
}

function devops.logs() {
    echo "📋 Fetching application logs..."
    kubectl logs -f deployment/app --tail=100
}

function devops.status() {
    echo "📊 System status check..."
    # Check your services, databases, etc.
}
EOF

# Add more plugins as needed - each must end with _chief-plugin.sh
# Plugin name will be "testing" (prefix before _chief-plugin.sh)
cat > tools/bash-plugins/testing_chief-plugin.sh << 'EOF'
#!/usr/bin/env bash
# Team Testing Tools

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  echo "Error: $(basename "${BASH_SOURCE[0]}") must be sourced, not executed."
  exit 1
fi

echo "Team Testing plugin loaded"

function testing.unit() {
    echo "🧪 Running unit tests..."
    npm test
}

function testing.integration() {
    echo "🔗 Running integration tests..."
    ./scripts/integration-tests.sh
}

alias testing.watch='npm run test:watch'
EOF

# Commit to your existing repo
git add tools/bash-plugins/
git commit -m "Add Chief plugins for team automation"
git push origin main

2. Team Member Configuration

Each team member points Chief to your existing repository:

# Configure Chief to use your existing team repo
chief.config_set plugins_git_repo "git@github.com:yourteam/existing-repo.git"
chief.config_set plugins_git_branch "main"
chief.config_set plugins_path "$HOME/team-repo"
chief.config_set plugins_git_path "tools/bash-plugins"  # Relative path to plugin files
chief.config_set plugins_git_autoupdate true

# Set to remote LAST - Chief will offer to update plugins when git config is ready
chief.config_set plugins_type remote

# Restart terminal or reload Chief
chief.reload

# Your team functions are now available!
devops.deploy
testing.unit

3. Plugin File Discovery Rules

Chief automatically discovers and loads files with specific naming:

# ✅ These files WILL be loaded:
devops_chief-plugin.sh       # Plugin name: "devops"
testing_chief-plugin.sh      # Plugin name: "testing"
monitoring_chief-plugin.sh   # Plugin name: "monitoring"  
k8s_chief-plugin.sh         # Plugin name: "k8s"

# ❌ These files will NOT be loaded:
devops.sh                   # Missing _chief-plugin.sh suffix
testing_plugin.sh           # Missing chief- prefix  
readme.md                   # Not a shell script
utilities.bash              # Wrong file extension

🔑 Important: The prefix before _chief-plugin.sh becomes the plugin name.

🆕 Scenario B: New Repository

Perfect when starting fresh with a dedicated plugins repository.

1. Create New Team Plugins Repository

# Create and set up new repository
mkdir my-team-bash-plugins
cd my-team-bash-plugins

# Initialize git
git init
git remote add origin git@github.com:yourteam/team-bash-plugins.git

# Create team plugins
cat > devops_chief-plugin.sh << 'EOF'
#!/usr/bin/env bash
# Team DevOps Tools

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  echo "Error: $(basename "${BASH_SOURCE[0]}") must be sourced, not executed."
  exit 1
fi

echo "Team DevOps plugin loaded"

function devops.deploy() {
    local environment="${1:-staging}"
    echo "🚀 Deploying to ${environment}..."
    # Team deployment logic
}

function devops.logs() {
    local service="${1:-app}"
    echo "📋 Fetching logs for ${service}..."
    kubectl logs -f "deployment/${service}" --tail=100
}
EOF

# Add team secrets (encrypted vault)
chief.vault_file-edit .chief_shared-vault
# Add shared environment variables, API keys, etc.

# Commit and push
git add .
git commit -m "Initial team plugins and vault"
git push -u origin main

2. Team Member Setup

# Configure Chief for team repository
chief.config_set plugins_git_repo "git@github.com:yourteam/team-bash-plugins.git"
chief.config_set plugins_path "$HOME/team_plugins"
chief.config_set plugins_git_autoupdate true
chief.config_set plugins_type remote

# Team functions and vault are now available
devops.deploy production

🔒 Vault Configuration

Creating and Managing Vaults

# Create team vault (encrypted)
chief.vault_file-edit .chief_shared-vault

# Create personal vault
chief.vault_file-edit ~/.my-personal-vault

# Load vaults
chief.vault_file-load .chief_shared-vault
chief.vault_file-load ~/.my-personal-vault

Team Vault Best Practices

🎯 Configuration Examples

Developer Workstation

# Enable all productivity features
chief.config_set prompt true
chief.config_set git_prompt true
chief.config_set multiline_prompt true
chief.config_set colored_ls true
chief.config_set ssh_keys_path "$HOME/.ssh"
chief.config_set alias "cf"

Server/CI Environment

# Minimal configuration for automation
chief.config_set banner false
chief.config_set hints false
chief.config_set prompt false
chief.config_set config_set_interactive false
chief.config_set plugins_git_autoupdate true

Team Lead Setup

# Full team collaboration features
chief.config_set plugins_type "remote"
chief.config_set plugins_git_repo "git@github.com:yourteam/plugins.git"
chief.config_set plugins_git_autoupdate true
chief.config_set autocheck_updates true

🔧 Troubleshooting Configuration

Common Configuration Issues

# Check current configuration
chief.config_show

# Reset configuration to defaults
cp ~/.chief/templates/chief_config_template.sh ~/.chief_config.sh

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

# Update configuration after upgrade
chief.config_update

Plugin Sync Issues

# Check plugin repository status
cd "$CHIEF_CFG_PLUGINS_PATH"
git status

# Force update plugins
chief.plugins_update --force

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

🎯 Next Steps

← Back to Home