Configuration Management

← Developer Experience | Home | Alias Management →

Overview

DotRun v3.1.0 uses a simple, file-based configuration system using plain Bash exports. Configuration files are automatically sourced at shell startup, providing a clean and maintainable way to manage environment variables, PATH configuration, API keys, and development tool settings.

Key Features:

File-based: Config files in ~/.config/dotrun/configs/
Auto-loaded: Sourced automatically via ~/.drrc at shell startup
Load order: NN-category naming controls load sequence
Simple syntax: Plain Bash export statements only
Category-based: Organize by purpose (paths, api, development, cloud)

Critical: PATH must be configured first (in 01-paths.config) before any other configs that depend on it.

v3.1.0 File-Based Workflow

Configuration in DotRun v3.1.0 works as follows:

At shell startup: ~/.drrc sources every *.config file in ~/.config/dotrun/configs/
Load order: Files are loaded in lexicographic order (01, 02, 03, ... 10, 11, ...)
Plain Bash: Each file contains simple export statements
Categories: Organize by topic (paths, api, development, cloud, local)
PATH baseline: Established in 01-paths.config before everything else

This approach replaces any hypothetical v2.x command-driven or YAML/JSON config systems with a straightforward, maintainable pattern.

File Structure and Naming

Directory: ~/.config/dotrun/configs/

Naming Convention: NN-category.config

NN: Two-digit number (01-99) controlling load order
category: Descriptive name (lowercase, hyphens allowed)
extension: .config

Example Structure:

~/.config/dotrun/configs/
├── 01-paths.config          # PATH configuration (MUST load first)
├── 02-xdg.config            # XDG base directories
├── 05-api.config            # API keys and tokens
├── 10-development.config    # Development tools
├── 20-cloud.config          # Cloud provider configs
└── 90-local.config          # Machine-specific overrides

Numbering Guidelines:

00-09: Core/baseline (paths, XDG)
10-49: Development tools and languages
50-79: Services and middleware
80-89: Team/project overrides
90-99: Local machine-specific overrides

Load Order Control

Files are sourced in lexicographic order by filename. The numeric prefix enforces the sequence.

Why Order Matters:

PATH Dependencies: Tools and scripts depend on PATH being set correctly
Variable References: Later configs can reference variables from earlier configs
Intentional Overrides: Later files can override earlier exports

Critical Rule: All PATH setup must happen in 01-paths.config before any other config that:

Appends to PATH
Executes commands found via PATH
Loads tools that modify PATH (nvm, pyenv, etc.)

Numbering Strategy:

# Good: Clear ordering with room for additions
01-paths.config       # Baseline PATH
02-xdg.config         # XDG directories
05-api.config         # API keys
10-development.config # Dev tools
15-languages.config   # Language-specific (if needed later)
20-cloud.config       # Cloud providers
90-local.config       # Local overrides

# Bad: No room for additions
1-paths.config
2-xdg.config
3-api.config
# What happens when you need something between 1 and 2?

Creating Config Files

DotRun v3.1.0 has no command interface for config management. Create and edit files manually.

Step 1: Ensure Directory Exists

mkdir -p ~/.config/dotrun/configs

Step 2: Create Config File

# Use your preferred editor
$EDITOR ~/.config/dotrun/configs/01-paths.config

# Or directly
vim ~/.config/dotrun/configs/05-api.config

Step 3: Reload Shell

# Option 1: Reload in current shell
source ~/.drrc

# Option 2: Start new shell (cleaner)
exec $SHELL

Step 4: Verify

# Check specific variable
echo "$EDITOR"

# Check PATH
echo "$PATH"

# Check all environment variables
env | grep -E '^(GITHUB_TOKEN|AWS_|EDITOR|GOPATH)'

Shell Integration Check:

If configs aren't loading, ensure ~/.drrc is sourced in your shell's RC file:

# Add to ~/.bashrc or ~/.zshrc
[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"

File Format

Config files use plain Bash syntax with export statements.

Basic Export:

export EDITOR="vim"
export VISUAL="$EDITOR"

PATH Operations:

# Prepend to PATH
export PATH="$HOME/.local/bin:$PATH"

# Append to PATH
export PATH="$PATH:$HOME/tools/bin"

# Set PATH from scratch (only in 01-paths.config!)
export PATH="/usr/local/bin:/usr/bin:/bin"

Quoted Values (for safety):

# Always quote values with spaces or special characters
export PROJECT_NAME="My Awesome Project"
export DATABASE_URL="postgresql://user:pass@localhost/db"

Optional Guarded Sourcing:

# Load external scripts if they exist
[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"

Best Practices:

Always use export for variables visible to child processes
Quote all string values
Keep commands minimal; prefer straight exports
Add comments explaining non-obvious choices

Managing Configs

Listing Configs:

# View all config files in load order
ls -1 ~/.config/dotrun/configs

# Or with details
ls -lh ~/.config/dotrun/configs/*.config

Editing Configs:

# Edit specific file
$EDITOR ~/.config/dotrun/configs/10-development.config

# Edit with vim
vim ~/.config/dotrun/configs/05-api.config

Reloading Configs:

# Reload in current shell
source ~/.drrc

# Or start fresh shell (preferred)
exec $SHELL

Validating Configs:

# Check syntax without executing
bash -n ~/.config/dotrun/configs/10-development.config

# View PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Search for specific exports
grep -R "export GITHUB_TOKEN" ~/.config/dotrun/configs

Removing Configs:

# Delete file
rm ~/.config/dotrun/configs/20-cloud.config

# Or rename to disable without deleting
mv ~/.config/dotrun/configs/05-api.config{,.disabled}

Common Config Patterns

1. PATH Configuration (01-paths.config)

Purpose: Establish baseline PATH that works across platforms. MUST load first.

# ~/.config/dotrun/configs/01-paths.config
# PATH Configuration - MUST LOAD FIRST
# Last Updated: 2024-01-15

# System baseline
export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

# User-level binaries (highest priority)
export PATH="$HOME/.local/bin:$PATH"

# Language-specific paths
export PATH="$HOME/.cargo/bin:$PATH"      # Rust
export PATH="$HOME/go/bin:$PATH"          # Go
export PATH="$HOME/.npm-global/bin:$PATH" # npm global

# Homebrew (macOS)
# Intel Macs
export PATH="/usr/local/bin:$PATH"
# Apple Silicon Macs
export PATH="/opt/homebrew/bin:$PATH"

# Project-local binaries
export PATH="./node_modules/.bin:$PATH"

# Snap packages (Linux)
export PATH="/snap/bin:$PATH"

2. XDG Directories (02-xdg.config)

Purpose: Normalize XDG base directories for cleaner home directory.

# ~/.config/dotrun/configs/02-xdg.config
# XDG Base Directory Specification
# Ensures consistent locations for config, cache, and data

export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_CACHE_HOME="$HOME/.cache"
export XDG_STATE_HOME="$HOME/.local/state"

# Optional: Configure tools to use XDG paths
export LESSHISTFILE="$XDG_STATE_HOME/less/history"
export DOCKER_CONFIG="$XDG_CONFIG_HOME/docker"
export NPM_CONFIG_USERCONFIG="$XDG_CONFIG_HOME/npm/npmrc"

3. API Keys (05-api.config)

Purpose: Central location for API tokens and service credentials.

⚠️ SECURITY WARNING: This file contains plain text secrets. Never commit to git!

# ~/.config/dotrun/configs/05-api.config
# API Keys and Tokens (SENSITIVE - DO NOT COMMIT)
# File permissions: chmod 600 05-api.config

# GitHub
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# OpenAI
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# AWS (use aws-vault or similar for production)
export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AWS_DEFAULT_REGION="us-east-1"

# Sentry
export SENTRY_AUTH_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# npm
export NPM_TOKEN="npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Database (development only!)
export DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"

# Note: Consider using secrets management tools instead:
# - 1Password CLI: op read "op://vault/item/field"
# - AWS Secrets Manager: aws secretsmanager get-secret-value
# - HashiCorp Vault: vault kv get secret/path

4. Development Tools (10-development.config)

Purpose: Development environment settings and tool configuration.

# ~/.config/dotrun/configs/10-development.config
# Development Tools and Preferences

# Editor and pager
export EDITOR="vim"
export VISUAL="code --wait"
export PAGER="less -RFX"

# Go
export GOPATH="$HOME/go"
export GOBIN="$GOPATH/bin"
export GO111MODULE="on"

# Node.js (pnpm example)
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# Python
export PIPX_HOME="$HOME/.local/pipx"
export PIPX_BIN_DIR="$HOME/.local/bin"
export PYTHONUNBUFFERED=1

# Ruby
export GEM_HOME="$HOME/.gem"
export PATH="$GEM_HOME/bin:$PATH"

# Rust
export CARGO_HOME="$HOME/.cargo"
export RUSTUP_HOME="$HOME/.rustup"

# Build tools
export MAKEFLAGS="-j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)"

# Development mode
export NODE_ENV="development"
export RUST_BACKTRACE="1"
export PYTHONDONTWRITEBYTECODE=1

# Optional: Load version managers
[ -s "$HOME/.nvm/nvm.sh" ] && . "$HOME/.nvm/nvm.sh"
[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"

5. Cloud Providers (20-cloud.config)

Purpose: Cloud provider configuration and preferences.

# ~/.config/dotrun/configs/20-cloud.config
# Cloud Provider Configuration

# AWS
export AWS_PROFILE="default"
export AWS_DEFAULT_REGION="us-east-1"
export AWS_DEFAULT_OUTPUT="json"
export AWS_CONFIG_FILE="$HOME/.aws/config"
export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/credentials"

# Google Cloud Platform
export CLOUDSDK_CONFIG="$HOME/.config/gcloud"
export CLOUDSDK_CORE_PROJECT="my-project"
export CLOUDSDK_COMPUTE_REGION="us-central1"
export CLOUDSDK_COMPUTE_ZONE="us-central1-a"

# Azure
export AZURE_CONFIG_DIR="$HOME/.azure"

# Terraform
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
# export TF_VAR_environment="development"

# Kubernetes
export KUBECONFIG="$HOME/.kube/config"

# Docker
export DOCKER_CONFIG="$XDG_CONFIG_HOME/docker"
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

6. Local Overrides (90-local.config)

Purpose: Machine-specific overrides that load last. Never commit this file.

# ~/.config/dotrun/configs/90-local.config
# Machine-Specific Overrides (DO NOT COMMIT)
# Loads last to override previous settings

# Corporate proxy (if needed)
# export HTTP_PROXY="http://proxy.company.com:8080"
# export HTTPS_PROXY="$HTTP_PROXY"
# export NO_PROXY="localhost,127.0.0.1,.company.com"

# Machine-specific PATH additions
# export PATH="/opt/company-tools/bin:$PATH"

# Override editor on work laptop
# export EDITOR="code --wait"
# export VISUAL="$EDITOR"

# Local API endpoint for development
# export API_BASE_URL="http://localhost:3000"

# Override AWS profile for this machine
# export AWS_PROFILE="personal"

# macOS Apple Silicon specific
# export PATH="/opt/homebrew/bin:$PATH"

# Local database connection
# export DATABASE_URL="postgresql://localhost/myapp_local"

Load Order Examples

✅ Good: PATH First, Dependencies Later

01-paths.config          # Sets PATH baseline
02-xdg.config            # XDG directories
05-api.config            # API keys
10-development.config    # Adds Go/Node/Python to PATH
20-cloud.config          # Uses cloud CLIs from PATH
90-local.config          # Local overrides

Why it works:

PATH is ready before any tools try to use it
Development configs can safely append to PATH
Cloud configs can execute tools found via PATH
Local overrides take precedence over earlier settings

❌ Bad: Tools Before PATH

10-development.config    # Tries to use tools
01-paths.config          # Sets PATH too late!
20-cloud.config

What breaks:

Development config tries to run go or node before PATH is set
Tools may not be found or wrong versions execute
PATH modifications happen in wrong order
command -v checks fail unexpectedly

❌ Bad: Sourcing Before PATH Baseline

05-api.config
10-development.config    # Contains: [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
01-paths.config          # Sets PATH last

What breaks:

nvm.sh sourcing can fail if it expects PATH to be configured
NVM_DIR may not be set or may point to wrong location
Tools added by nvm won't be found in correct order
Inconsistent behavior across different terminal sessions

Security Considerations

Configuration files may contain sensitive information. Follow these security practices.

File Permissions

Restrict access to sensitive config files:

# Lock down entire configs directory
chmod 700 ~/.config/dotrun
chmod 700 ~/.config/dotrun/configs

# Sensitive files should be user-readable only
chmod 600 ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/90-local.config

Version Control

Never commit secrets to git:

# Add to .gitignore
~/.config/dotrun/configs/05-api.config
~/.config/dotrun/configs/90-local.config
~/.config/dotrun/configs/*local.config
~/.config/dotrun/configs/*secrets.config

Secrets Management Alternatives

Instead of plain text secrets, use secure alternatives:

1Password CLI:

# Store in 1Password, retrieve at runtime
export GITHUB_TOKEN="$(op read 'op://Personal/GitHub/token')"
export AWS_SECRET_ACCESS_KEY="$(op read 'op://Work/AWS/secret_key')"

macOS Keychain:

# Store once
security add-generic-password -a "$USER" -s "github-token" -w "ghp_xxxxx"

# Retrieve in config
export GITHUB_TOKEN="$(security find-generic-password -a "$USER" -s "github-token" -w)"

Linux Secret Service:

# Store once
secret-tool store --label="GitHub Token" service dotrun username github

# Retrieve in config
export GITHUB_TOKEN="$(secret-tool lookup service dotrun username github)"

AWS Secrets Manager:

# Retrieve from AWS
export DATABASE_PASSWORD="$(aws secretsmanager get-secret-value \
  --secret-id prod/db/password \
  --query SecretString \
  --output text)"

HashiCorp Vault:

# Retrieve from Vault
export API_KEY="$(vault kv get -field=key secret/api/production)"

Best Practices

Minimal Secrets: Only store secrets you absolutely need in config files
Scoped Tokens: Use tokens with minimal permissions
Rotation: Rotate credentials regularly
Avoid Logging: Never echo secret values to logs
Disable Debug: Avoid set -x when sourcing configs (prints all variables)
Separate Files: Keep secrets in separate files (05-api.config, 90-local.config)
Audit: Regularly review who has access to config files

Security Checklist

# ✅ File permissions locked down
ls -la ~/.config/dotrun/configs/*.config | grep "^-rw-------"

# ✅ Secrets not in git
git status ~/.config/dotrun/configs/

# ✅ No world-readable files
find ~/.config/dotrun -type f -perm -004

# ✅ No secrets in shell history
grep -i "export.*token\|export.*key\|export.*password" ~/.bash_history

Migration from v2.x

If you're migrating from a hypothetical v2.x system with command-driven configs or YAML/JSON patterns:

What Changed

v2.x (hypothetical):

Command-driven: dr config set KEY value
Complex formats: YAML/JSON configs
Special variables: DR_HOME, DR_BIN, DR_DOCS
Tool-managed: Configs stored in database or single file

v3.1.0 (actual):

File-based: Manual .config files
Simple format: Plain Bash export statements
Standard paths: ~/.config/dotrun/configs/
User-managed: Direct file editing

Migration Steps

Step 1: Disable v2.x Hooks

# Edit shell RC files
vim ~/.bashrc # or ~/.zshrc

# Comment out or remove v2.x-specific lines
# OLD: source ~/.dotrun/env
# OLD: eval "$(dr config load)"

Step 2: Create v3.1.0 Files

# Create directory
mkdir -p ~/.config/dotrun/configs

# Create core files
touch ~/.config/dotrun/configs/01-paths.config
touch ~/.config/dotrun/configs/02-xdg.config
touch ~/.config/dotrun/configs/05-api.config
touch ~/.config/dotrun/configs/10-development.config
touch ~/.config/dotrun/configs/20-cloud.config
touch ~/.config/dotrun/configs/90-local.config

Step 3: Translate Variables

# OLD v2.x (hypothetical)
dr config set EDITOR vim
dr config set API_KEY sk-xxxxx
dr config set GOPATH ~/go

# NEW v3.1.0 (in 10-development.config)
export EDITOR="vim"
export GOPATH="$HOME/go"

# NEW v3.1.0 (in 05-api.config)
export API_KEY="sk-xxxxx"

Step 4: Set PATH Explicitly

# OLD v2.x: May have managed PATH automatically
# NEW v3.1.0: Explicit in 01-paths.config

# ~/.config/dotrun/configs/01-paths.config
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"

Step 5: Test and Validate

# Reload configs
source ~/.drrc

# Verify variables
echo "$EDITOR"
echo "$GOPATH"
env | grep -E '^(API_KEY|GITHUB_TOKEN|AWS_)'

# Verify PATH
printf "%s\n" "${PATH//:/$'\n'}"

# Test in new shell
exec $SHELL

Step 6: Clean Up

# Remove obsolete v2.x files
rm -rf ~/.dotrun/               # If this was v2.x location
rm ~/.config/dotrun/config.yml  # If YAML configs existed
rm ~/.config/dotrun/config.json # If JSON configs existed

# Clean shell history (optional)
history -c

Variable Translation Table

v2.x Variable	v3.1.0 Approach
`DR_HOME`	Not used; use `~/.config/dotrun` directly
`DR_BIN`	Not used; scripts in `~/.config/dotrun/scripts`
`DR_DOCS`	Not used
Custom configs	Export in appropriate `.config` file
Secrets	Store in `05-api.config` or use secrets manager

Best Practices

1. PATH First Always

# ✅ GOOD: PATH in 01-paths.config
# ~/.config/dotrun/configs/01-paths.config
export PATH="$HOME/.local/bin:$PATH"

# ❌ BAD: PATH in 10-development.config
# Wrong numeric prefix - tools may fail before this loads

2. Keep It Simple

# ✅ GOOD: Direct exports
export EDITOR="vim"
export GOPATH="$HOME/go"

# ❌ BAD: Complex logic
if [ -x "$(command -v code)" ]; then
  export EDITOR="$(which code) --wait"
elif [ -x "$(command -v vim)" ]; then
  export EDITOR="vim"
else
  export EDITOR="nano"
fi
# This belongs in a script, not a config file

3. Focused Categories

# ✅ GOOD: Many focused files
01-paths.config       # Only PATH
02-xdg.config         # Only XDG
05-api.config         # Only secrets
10-development.config # Only dev tools

# ❌ BAD: One huge file
00-everything.config # 500 lines of mixed concerns

4. Separate Secrets

# ✅ GOOD: Secrets isolated
05-api.config   # All secrets here
90-local.config # Machine-specific secrets
# Both excluded from git

# ❌ BAD: Secrets scattered
10-development.config # export GITHUB_TOKEN="..."
20-cloud.config       # export AWS_SECRET_KEY="..."
# Hard to manage, easy to accidentally commit

5. Use Absolute Paths

# ✅ GOOD: Absolute with $HOME
export GOPATH="$HOME/go"
export CARGO_HOME="$HOME/.cargo"

# ❌ BAD: Relative or tilde in exports
export GOPATH="~/go"          # Tilde may not expand correctly
export CARGO_HOME="../.cargo" # Relative paths break

6. Idempotent Sourcing

# ✅ GOOD: Safe to source multiple times
export PATH="$HOME/.local/bin:$PATH"
# Each re-source just prepends again (mostly harmless)

# ✅ BETTER: Check before adding to PATH (advanced)
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
  export PATH="$HOME/.local/bin:$PATH"
fi

# Note: Generally prefer opening new shell over re-sourcing

7. Validate Frequently

# Check syntax before sourcing
bash -n ~/.config/dotrun/configs/10-development.config

# View PATH clearly
printf "%s\n" "${PATH//:/$'\n'}"

# Search for duplicates
grep -R "export EDITOR" ~/.config/dotrun/configs

8. Document Choices

# ✅ GOOD: Commented and explained
# ~/.config/dotrun/configs/01-paths.config
# PATH Configuration - MUST LOAD FIRST
# Last Updated: 2024-01-15

# Homebrew (Apple Silicon M1/M2/M3)
export PATH="/opt/homebrew/bin:$PATH"

# ❌ BAD: No context
export PATH="/opt/homebrew/bin:$PATH"

9. File Permissions

# Lock down sensitive files
chmod 600 ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/90-local.config

# Verify
ls -la ~/.config/dotrun/configs/*.config

10. Version Control Strategy

# Track non-secret configs
git add ~/.config/dotrun/configs/01-paths.config
git add ~/.config/dotrun/configs/02-xdg.config
git add ~/.config/dotrun/configs/10-development.config
git add ~/.config/dotrun/configs/20-cloud.config

# Never track secrets
echo "configs/05-api.config" >>.gitignore
echo "configs/90-local.config" >>.gitignore
echo "configs/*local.config" >>.gitignore
echo "configs/*secrets.config" >>.gitignore

Troubleshooting

Files Aren't Loading

Symptom: Environment variables not set after opening new terminal.

Diagnosis:

# Check if ~/.drrc exists
ls -la ~/.drrc

# Check if shell sources it
grep -i "drrc" ~/.bashrc ~/.zshrc

# List config files
ls -1 ~/.config/dotrun/configs/*.config

Fix:

# Ensure ~/.drrc is sourced in shell RC
echo '[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"' >>~/.bashrc
# or for zsh:
echo '[ -f "$HOME/.drrc" ] && . "$HOME/.drrc"' >>~/.zshrc

# Reload shell
exec $SHELL

Wrong Load Order

Symptom: Variables undefined or PATH wrong despite being in configs.

Diagnosis:

# Check load order
ls -1 ~/.config/dotrun/configs

# Should be: 01-paths.config, 02-xdg.config, etc.
# NOT: 1-paths.config, 10-development.config, 2-xdg.config

Fix:

# Rename to use two-digit prefixes
mv ~/.config/dotrun/configs/1-paths.config \
  ~/.config/dotrun/configs/01-paths.config

mv ~/.config/dotrun/configs/2-xdg.config \
  ~/.config/dotrun/configs/02-xdg.config

# Reload
source ~/.drrc

PATH Not Correct

Symptom: Commands not found or wrong versions executing.

Diagnosis:

# View PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Check if 01-paths.config exists
cat ~/.config/dotrun/configs/01-paths.config

# Look for PATH resets (PATH= without $PATH)
grep -n "^export PATH=" ~/.config/dotrun/configs/*.config

Fix:

# Ensure PATH set in 01-paths.config
vim ~/.config/dotrun/configs/01-paths.config

# Use this pattern (prepend):
export PATH="$HOME/.local/bin:$PATH"

# NOT this (reset):
export PATH="$HOME/.local/bin" # Wrong! Loses system paths

# Reload
source ~/.drrc

Variables Not Set

Symptom: echo "$VAR" shows empty despite being in config file.

Diagnosis:

# Check syntax
bash -n ~/.config/dotrun/configs/10-development.config

# Look for the export
grep "EDITOR" ~/.config/dotrun/configs/*.config

# Check if file is being loaded
ls ~/.config/dotrun/configs/*.config

Fix:

# Ensure correct export syntax
# ✅ GOOD
export EDITOR="vim"

# ❌ BAD (missing export)
EDITOR="vim"

# ❌ BAD (missing quotes)
export EDITOR=vim with flags

# Reload
source ~/.drrc

Secrets Missing

Symptom: API calls fail with authentication errors.

Diagnosis:

# Check if secrets file exists
ls -la ~/.config/dotrun/configs/05-api.config

# Check permissions
ls -la ~/.config/dotrun/configs/05-api.config
# Should show: -rw------- (600)

# Check if variable set (safely)
[ -n "$GITHUB_TOKEN" ] && echo "Set" || echo "Not set"

Fix:

# Create if missing
touch ~/.config/dotrun/configs/05-api.config
chmod 600 ~/.config/dotrun/configs/05-api.config

# Add export statements
export GITHUB_TOKEN="ghp_xxxxx"

# Reload
source ~/.drrc

Syntax Errors

Symptom: Error messages when opening terminal or sourcing configs.

Diagnosis:

# Test each file individually
bash -n ~/.config/dotrun/configs/01-paths.config
bash -n ~/.config/dotrun/configs/10-development.config

# Look for common issues
grep -n "export" ~/.config/dotrun/configs/*.config

Common Issues:

# ❌ Unmatched quotes
export VAR="value with "quotes" inside"
# Fix: Escape inner quotes
export VAR="value with \"quotes\" inside"

# ❌ Missing closing quote
export VAR="value
# Fix: Close quote on same line
export VAR="value"

# ❌ Spaces around =
export VAR = "value"
# Fix: No spaces
export VAR="value"

Shell-Specific Issues

Bash vs Zsh:

# Export syntax is the same
export VAR="value" # Works in both

# But sourcing differs slightly
# Bash: source or .
source ~/.drrc
. ~/.drrc

# Zsh: source or .
source ~/.drrc
. ~/.drrc

# Both work with both shells for basic configs

Duplicate Entries

Symptom: PATH contains same directory multiple times.

Diagnosis:

# Check for duplicates
printf "%s\n" "${PATH//:/$'\n'}" | sort | uniq -c | grep -v "^ *1 "

Fix:

# Use conditional PATH additions (advanced)
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
  export PATH="$HOME/.local/bin:$PATH"
fi

# Or: Prefer new shell over re-sourcing
exec $SHELL # Instead of: source ~/.drrc

Quick Verification Commands

# Show load order
ls -1 ~/.config/dotrun/configs

# Show PATH line-by-line
printf "%s\n" "${PATH//:/$'\n'}"

# Check for conflicts
grep -R "export EDITOR" ~/.config/dotrun/configs

# Reload configs
source ~/.drrc

# Test in fresh shell
exec $SHELL

# Validate syntax
for f in ~/.config/dotrun/configs/*.config; do
  echo "Checking: $f"
  bash -n "$f" || echo "Syntax error in $f"
done

Next Steps

With configuration management set up:

Manage Aliases: Set up Alias Management using similar NN-category pattern
Secure Secrets: Review Security Best Practices for secrets management
Script Development: Use configs in Script Development
Collections: Share configs via Collections
Team Setup: Coordinate Team Workflows with shared configs

← Developer Experience | Alias Management → | Top ↑

Uh oh!

Configuration Management

Configuration Management

Table of Contents

Overview

v3.1.0 File-Based Workflow

File Structure and Naming

Load Order Control

Creating Config Files

File Format

Managing Configs

Common Config Patterns

1. PATH Configuration (01-paths.config)

2. XDG Directories (02-xdg.config)

3. API Keys (05-api.config)

4. Development Tools (10-development.config)

5. Cloud Providers (20-cloud.config)

6. Local Overrides (90-local.config)

Load Order Examples

✅ Good: PATH First, Dependencies Later

❌ Bad: Tools Before PATH

❌ Bad: Sourcing Before PATH Baseline

Security Considerations

File Permissions

Version Control

Secrets Management Alternatives

Best Practices

Security Checklist

Migration from v2.x

What Changed

Migration Steps

Variable Translation Table

Best Practices

1. PATH First Always

2. Keep It Simple

3. Focused Categories

4. Separate Secrets

5. Use Absolute Paths

6. Idempotent Sourcing

7. Validate Frequently

8. Document Choices

9. File Permissions

10. Version Control Strategy

Troubleshooting

Files Aren't Loading

Wrong Load Order

PATH Not Correct

Variables Not Set

Secrets Missing

Syntax Errors

Shell-Specific Issues

Duplicate Entries

Quick Verification Commands

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!