Skip to content

Quick Reference

Jump to bottom
Joao Palma edited this page Jan 29, 2026 · 4 revisions

Quick Reference

Essential DotRun commands and patterns at a glance

Core Commands

Script Execution

dr script-name [args...]  # Run a script
dr category/script-name   # Run categorized script
dr collection/script-name # Run script from collection

Script Management

dr set script-name          # Create new script or edit existing
dr set category/script-name # Create script in category or edit existing
dr move old-name new-name   # Move/rename script (preserves docs)
dr copy source target       # Copy script to new location
dr remove script-name       # Delete script (with confirmation)

Information & Discovery

dr -l                # List script names
dr -L                # List scripts with descriptions
dr help script-name  # Show script help
dr docs script-name  # Show formatted documentation
dr which script-name # Show script file path

Collection Management

Basic Collection Operations

dr import <repo-url> <name>   # Import collection from Git
dr collections list           # List all collections
dr collections info <name>    # Show collection details
dr collections update <name>  # Update specific collection
dr collections update-all     # Update all collections
dr collections remove <name>  # Remove collection

Collection Examples

# Import from GitHub
dr import https://github.com/user/scripts.git team-tools

# Import from private repository
dr import git@github.com:company/tools.git company

# Import specific branch/tag
dr import -b development https://github.com/user/scripts.git dev-tools

File Locations

Directory Structure

~/.config/dotrun/
├── dr   # Main executable
├── bin/ # Personal scripts
│ ├── category1/
│ ├── category2/
│ └── script.sh
├── docs/           # Script documentation
├── collections/    # Imported collections
├── helpers/        # Utility libraries
└── dr_completion.* # Shell completions

Important Files

~/.config/dotrun/dr                # Main DotRun executable
~/.local/bin/dr                    # Symlink to main executable
~/.config/dotrun/bin/script.sh     # Personal script
~/.config/dotrun/docs/script.md    # Script documentation
~/.config/dotrun/collections/name/ # Collection directory

Script Template

Basic Script Structure

#!/usr/bin/env bash
### DOC
# Brief description of what this script does
# Usage: dr script-name [options] [arguments]
#
# Examples:
#   dr script-name
#   dr script-name --verbose file.txt
#
# Requirements: git, docker
### DOC
set -euo pipefail

main() {
  local arg1="${1:-default}"
  local flag_verbose=false

  # Parse arguments
  while [[ $# -gt 0 ]]; do
    case $1 in
      --verbose | -v)
        flag_verbose=true
        shift
        ;;
      --help | -h)
        show_help
        exit 0
        ;;
      *)
        # Handle positional arguments
        break
        ;;
    esac
  done

  # Script logic here
  echo "✅ Script completed successfully!"
}

show_help() {
  cat <<EOF
Usage: dr script-name [options] [arguments]

Description goes here.

Options:
    -v, --verbose    Enable verbose output
    -h, --help       Show this help

Examples:
    dr script-name
    dr script-name --verbose file.txt
EOF
}

main "$@"

Common Patterns

Error Handling

# Exit on any error
set -euo pipefail

# Custom error function
error() {
  echo "❌ Error: $1" >&2
  [[ -n "${2:-}" ]] && echo "💡 Suggestion: $2" >&2
  exit 1
}

# Usage
[[ -f "$file" ]] || error "File not found: $file" "Check the file path"

Dependency Checking

# Using DotRun helper
source "$DR_CONFIG/helpers/pkg.sh"
validatePkg git docker kubectl

# Manual checking
check_deps() {
  for cmd in git docker kubectl; do
    command -v "$cmd" >/dev/null || error "Missing dependency: $cmd"
  done
}

Input Validation

# Required parameter
[[ -z "${1:-}" ]] && error "Usage: dr script-name <required-param>"

# File/directory existence
[[ -f "$config_file" ]] || error "Config file not found: $config_file"
[[ -d "$target_dir" ]] || error "Directory not found: $target_dir"

# Valid options
case "$environment" in
  staging | production) ;;
  *) error "Invalid environment: $environment" "Use 'staging' or 'production'" ;;
esac

Progress Indicators

# Simple progress
echo "🚀 Starting deployment..."
echo "📦 Building application..."
echo "☁️  Uploading to cloud..."
echo "✅ Deployment complete!"

# Spinner (if installed)
if command -v spinner >/dev/null; then
  spinner "Building..." long_running_command
fi

Environment Variables

DotRun Variables

$DR_CONFIG  # DotRun config directory (~/.config/dotrun)
$DR_VERSION # DotRun version
$EDITOR     # Editor for script editing

Common Environment Patterns

# Environment-specific behavior
ENVIRONMENT="${ENVIRONMENT:-development}"
case "$ENVIRONMENT" in
  production) set_production_settings ;;
  staging) set_staging_settings ;;
  *) set_development_settings ;;
esac

# Debug mode
DEBUG="${DEBUG:-false}"
[[ "$DEBUG" == "true" ]] && set -x

Keyboard Shortcuts & Completion

Tab Completion

dr <TAB>                      # List all available scripts
dr git/<TAB>                  # List scripts in git category
dr set <TAB>                  # List scripts to create/edit
dr help <TAB>                 # List scripts with help

Shell Integration

# Add to ~/.bashrc or ~/.zshrc
source ~/.config/dotrun/dr_completion.bash # Bash
source ~/.config/dotrun/dr_completion.zsh  # Zsh

# Fish completion
cp ~/.config/dotrun/dr_completion.fish ~/.config/fish/completions/dr.fish

Integration Examples

Git Hooks

# .git/hooks/pre-commit
#!/usr/bin/env bash
dr validation/pre-commit-checks

CI/CD Integration

# GitHub Actions
- name: Setup DotRun
  run: curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh
- name: Run tests
  run: dr project/test-all

Docker

# Mount DotRun in container
docker run -v ~/.config/dotrun:/dotrun:ro ubuntu /dotrun/bin/script.sh

Cron Jobs

# Add to crontab
0 2 * * * /home/user/.local/bin/dr maintenance/daily-backup

Troubleshooting Quick Fixes

Common Issues

# Command not found
export PATH="$PATH:~/.local/bin"

# Permission denied
chmod +x ~/.config/dotrun/bin/script.sh

# Completion not working
source ~/.config/dotrun/dr_completion.bash

# Update DotRun
curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh

Debug Mode

# Enable bash debugging
export DR_DEBUG=1
dr script-name

# Or in script
set -x # Enable debugging
set +x # Disable debugging

Best Practices Checklist

Script Creation

  • Use descriptive, kebab-case names
  • Include ### DOC section with usage examples
  • Add set -euo pipefail for error handling
  • Check dependencies at script start
  • Validate inputs and provide clear error messages
  • Test script in clean environment before sharing

Team Collaboration

  • Use consistent naming conventions
  • Document all scripts thoroughly
  • Review scripts before adding to collections
  • Version collections with semantic versioning
  • Communicate changes to team members

Security

  • Never hardcode secrets or passwords
  • Validate all user inputs
  • Use secure temporary files (mktemp)
  • Set appropriate file permissions
  • Avoid dangerous operations without safeguards

Need More Help?

Keep this reference handy for quick lookups while working with DotRun!

Clone this wiki locally