Skip to content

API Reference

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

API Reference

Complete reference for all DotRun commands, options, and usage patterns. This page serves as the definitive command documentation.

Command Syntax

dr [OPTIONS] [COMMAND] [ARGUMENTS...]

Global Options

--help, -h

Display help information.

dr --help             # General help
dr script-name --help # Script-specific help (if script supports it)

--version, -v

Display DotRun version information.

dr --version
# Output: DotRun v3.1.0

--list, -l

List available scripts (short format).

dr -l        # List all scripts
dr -l folder # List scripts in specific folder

--list-detailed, -L

List available scripts with descriptions.

dr -L        # List all scripts with descriptions
dr -L folder # List scripts in folder with descriptions

Script Management Commands

Running Scripts (Default Action)

Execute a script. This is the default action when no command is specified.

Syntax:

dr <script-name>
dr <folder>/<script-name>
dr -s <script-name>

Examples:

# Run personal script
dr hello
dr git/branch-cleanup

# Run with arguments
dr utils/backup ~/Documents /backup/location

# Run with environment variables
ENV_VAR=value dr script-name

set <script-name>

Create or edit a script. Creates a new script if it doesn't exist, or opens an existing one for editing.

Syntax:

dr set <script-name>
dr set <folder>/<script-name>
dr -s set <script-name>

Examples:

dr set hello           # Creates/edits hello.sh
dr set git/branch-tool # Creates/edits git/branch-tool.sh
dr set deploy/staging  # Creates/edits deploy/staging.sh

What it does:

  • Creates executable script file in appropriate directory (if new)
  • Generates documentation template (if new)
  • Opens script in your $EDITOR

move <source> <destination>

Move or rename a script with all documentation.

Aliases: rename

Syntax:

dr move <source-script> <destination-script>
dr rename <source-script> <destination-script>
dr -s move <source-script> <destination-script>

Examples:

# Simple rename
dr move oldname newname

# Move to folder
dr move script git/script

# Rename and move
dr move old-script utils/new-script

# Reorganize folders
dr move git/old-tool docker/new-tool

What it does:

  • Moves script file to new location
  • Updates documentation path
  • Preserves file permissions
  • Creates directories as needed

rm <script-name>

Remove a script and its documentation.

Aliases: remove

Syntax:

dr rm <script-name>
dr remove <script-name>
dr -s rm <script-name>

Examples:

dr rm old-script
dr rm git/unused-tool

Safety:

  • Prompts for confirmation
  • Removes both script and documentation
  • Cannot be undone (unless using git)

help <script-name>

Display inline script documentation (from ### DOC sections).

Syntax:

dr help <script-name>
dr -s help <script-name>

Examples:

dr help git/branch-cleanup
# Shows usage, options, and examples from script comments

list (Short Format)

List available scripts in tree view.

Syntax:

dr -l [folder]
dr -s -l [folder]

Examples:

dr -l     # List all scripts
dr -l git # List scripts in git folder

Output:

git/
├── branch-cleanup
└── commit-helper
docker/
└── cleanup

list (Long Format)

List available scripts with descriptions in tree view.

Syntax:

dr -L [folder]
dr -s -L [folder]

Examples:

dr -L     # List all scripts with descriptions
dr -L git # List git folder scripts with descriptions

Output:

git/
├── branch-cleanup    - Clean up merged git branches
└── commit-helper     - Interactive commit assistant
docker/
└── cleanup          - Remove unused Docker containers

Alias Management Commands

Aliases provide a way to store and manage shell aliases in DotRun. The default action is ADD/EDIT when no command is specified.

Create/Edit Alias (Default Action)

Create or edit an alias file.

Syntax:

dr -a <filename>
dr -a <folder>/<filename>
dr --aliases <filename>

Examples:

dr -a git              # Create/edit git aliases
dr -a docker/shortcuts # Create/edit docker/shortcuts aliases

list Alias Files

List available alias files.

Syntax:

dr -a list

Output:

git
docker/shortcuts
utils/helpers

move Alias File

Move or rename an alias file.

Syntax:

dr -a move <source> <destination>

Examples:

dr -a move old-aliases new-aliases
dr -a move aliases git/aliases

rm Alias File

Remove an alias file.

Syntax:

dr -a rm <filename>

Examples:

dr -a rm old-aliases
dr -a rm docker/unused

help Alias File

Display help for an alias file.

Syntax:

dr -a help <filename>

Examples:

dr -a help git

init Alias Structure

Initialize the aliases folder structure.

Syntax:

dr -a init

What it does:

  • Creates the aliases directory structure
  • Sets up necessary configuration files

Config Management Commands

Configs allow you to manage configuration files in DotRun. The default action is ADD/EDIT when no command is specified.

Create/Edit Config (Default Action)

Create or edit a config file.

Syntax:

dr -c <filename>
dr -c <folder>/<filename>
dr --config <filename>

Examples:

dr -c api             # Create/edit api config
dr -c docker/settings # Create/edit docker/settings config

list Config Files

List available config files.

Syntax:

dr -c list

Output:

api
docker/settings
database/connection

move Config File

Move or rename a config file.

Syntax:

dr -c move <source> <destination>

Examples:

dr -c move old-config new-config
dr -c move config docker/config

rm Config File

Remove a config file.

Syntax:

dr -c rm <filename>

Examples:

dr -c rm old-config
dr -c rm docker/unused

help Config File

Display help for a config file.

Syntax:

dr -c help <filename>

Examples:

dr -c help api

init Config Structure

Initialize the configs folder structure.

Syntax:

dr -c init

What it does:

  • Creates the configs directory structure
  • Sets up necessary configuration files

Collection Management Commands

Collections are Git repositories containing reusable scripts that can be imported and managed.

add Collection

Install a collection from a Git repository.

Syntax:

dr -col add <repository-url>

Examples:

# Install from GitHub
dr -col add https://github.com/team/scripts.git

# Install from SSH
dr -col add git@github.com:team/scripts.git

What it does:

  • Clones repository to collections directory
  • Makes scripts available with collection-name/script-name syntax
  • Maintains separate git history

list Collections

List all installed collections.

Syntax:

dr -col list

Output:

Collection Name    Repository                              Last Updated
team-tools        git@github.com:team/scripts.git        2026-01-15
personal-extras   https://github.com/user/extras.git     2026-01-10

sync Collections

Check for updates to collections.

Syntax:

dr -col sync

What it does:

  • Checks all collections for available updates
  • Displays which collections have updates available
  • Does not automatically update (use update command)

update Collection

Update a collection from its remote repository.

Syntax:

dr -col update <collection-name>
dr -col update all

Examples:

# Update specific collection
dr -col update team-tools

# Update all collections
dr -col update all

remove Collection

Remove an installed collection.

Syntax:

dr -col remove <collection-name>
dr -col rm <collection-name>

Examples:

dr -col remove old-collection
dr -col rm team-tools

Safety:

  • Prompts for confirmation
  • Completely removes collection directory

Environment Variables

DR_CONFIG

Path to DotRun configuration directory.

Default: ~/.config/dotrun

Usage:

export DR_CONFIG="/custom/path"

EDITOR

Preferred text editor for script editing.

Default: vi or system default

Usage:

export EDITOR="code" # VS Code
export EDITOR="vim"  # Vim
export EDITOR="nano" # Nano

DR_DEBUG

Enable debug output.

Usage:

export DR_DEBUG=1
dr script-name # Shows debug output

Configuration Files

.drun-config

Global configuration file (optional).

Location: ~/.config/dotrun/.drun-config

Format:

# Default editor
EDITOR=code

# Custom settings
DEFAULT_TEMPLATE=advanced
AUTO_LINT=true

dotrun.collection.yml

Collection metadata file.

Location: collection-root/dotrun.collection.yml

Format:

name: "collection-name"
description: "Collection description"
author: "Author Name"
version: "1.0.0"
dependencies:
  - git
  - docker
  - kubectl
optional_dependencies:
  - glow
  - jq
categories:
  - deployment
  - git
  - docker

Exit Codes

DotRun uses standard Unix exit codes:

Code Meaning
0 Success
1 General error
2 Misuse of shell command
126 Script not executable
127 Script not found
128+ Fatal error signal

Script Requirements

File Structure

#!/usr/bin/env bash
### DOC
# Script description
# Usage: dr script-name [options]
### DOC
set -euo pipefail

main() {
  # Script logic here
  echo "Script executed successfully"
}

main "$@"

Required Elements

  1. Shebang Line: #!/usr/bin/env bash
  2. DOC Sections: Inline documentation between ### DOC markers
  3. Error Handling: set -euo pipefail recommended
  4. Main Function: Entry point function called with "$@"

Optional Elements

  1. Argument Parsing: Handle command-line options
  2. Help Function: Built-in help with --help flag
  3. Dependencies: Check for required tools
  4. Configuration: Load settings from environment or files

Advanced Usage Patterns

Argument Parsing Template

usage() {
  cat <<EOF
Usage: dr script-name [OPTIONS] [ARGUMENTS]

OPTIONS:
    -h, --help      Show this help
    -v, --verbose   Enable verbose output
    --option VALUE  Specify option value

EXAMPLES:
    dr script-name
    dr script-name --verbose
    dr script-name --option value
EOF
}

parse_args() {
  while [[ $# -gt 0 ]]; do
    case $1 in
      -h | --help)
        usage
        exit 0
        ;;
      -v | --verbose)
        VERBOSE=true
        shift
        ;;
      --option)
        OPTION_VALUE="$2"
        shift 2
        ;;
      *)
        echo "Unknown option: $1"
        usage
        exit 1
        ;;
    esac
  done
}

Error Handling

# Strict error handling
set -euo pipefail

# Custom error function
error() {
  echo "❌ Error: $1" >&2
  exit 1
}

# Usage
command || error "Command failed"
[[ -f "$file" ]] || error "File not found: $file"

Dependency Checking

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

# Manual checking
check_dependencies() {
  local deps=("git" "docker" "kubectl")
  for dep in "${deps[@]}"; do
    if ! command -v "$dep" >/dev/null 2>&1; then
      error "Required dependency not found: $dep"
    fi
  done
}

Integration Patterns

Git Workflow Scripts

# Access git helpers
source "$DR_CONFIG/helpers/git.sh"

# Common patterns
cd_repo_root # Change to git root
current_branch=$(git_current_branch)
default_branch=$(git_default_branch)

Docker Scripts

# Container management
docker_running() {
  docker ps --format "table {{.Names}}\t{{.Status}}" | grep -v NAMES
}

docker_cleanup() {
  docker container prune -f
  docker image prune -f
}

Configuration Management

# Load configuration
load_config() {
  local config_file="$HOME/.config/dotrun/.drun-config"
  [[ -f "$config_file" ]] && source "$config_file"
}

# Environment-specific settings
case "${ENVIRONMENT:-development}" in
  production)
    API_URL="https://api.prod.com"
    ;;
  staging)
    API_URL="https://api.staging.com"
    ;;
  *)
    API_URL="https://api.dev.com"
    ;;
esac

Troubleshooting Commands

Debug Script Execution

# Run with debug output
bash -x ~/.local/bin/dr script-name

# Check script syntax
bash -n ~/.config/dotrun/bin/script-name.sh

# Verbose DotRun execution
DR_DEBUG=1 dr script-name

Verify Installation

# Check DotRun installation
which dr
dr --version

# Check directory structure
ls -la ~/.config/dotrun/

# Test basic functionality
dr -l

Collection Debugging

# List collection details
dr -col list

# Check collection structure
ls -la ~/.config/dotrun/collections/collection-name/

# Verify collection scripts
find ~/.config/dotrun/collections -name "*.sh" -exec bash -n {} \;

Quick Reference Card

Scripts

Command Description
dr <name> Run script
dr set <name> Create/edit script
dr -l [folder] List scripts (short)
dr -L [folder] List scripts with descriptions
dr help <name> Show script help
dr move <old> <new> Move/rename script
dr rm <name> Remove script

Aliases

Command Description
dr -a <name> Create/edit alias file
dr -a list List alias files
dr -a move <old> <new> Move/rename alias file
dr -a rm <name> Remove alias file
dr -a help <name> Show alias help
dr -a init Initialize aliases

Configs

Command Description
dr -c <name> Create/edit config file
dr -c list List config files
dr -c move <old> <new> Move/rename config file
dr -c rm <name> Remove config file
dr -c help <name> Show config help
dr -c init Initialize configs

Collections

Command Description
dr -col add <url> Install collection
dr -col list List collections
dr -col sync Check for updates
dr -col update <name> Update collection
dr -col remove <name> Remove collection

For more examples and use cases, see the Quick Start Tutorial and Workflow Recipes.

Clone this wiki locally