DotRun CLI (dr) – Script Management Framework

Decision Routing Matrix

CRITICAL: Route ALL shell automation through dr.

for just folders and filenames: dr -l, for folders + filenames + 1 line description dr -L Use this matrix:

Trigger Detection

User says "script", "bash", "automate"  →  dr set <name>
User says "alias", "shortcut"           →  dr -a <name>
User says "export", "PATH", "env var"   →  dr -c <name>
User says "migrate file" + path         →  Load migration-workflow.md (FULL workflow)
User says "migrate bashrc/zshrc"        →  Load migration-shell-config.md
User says "import scripts from ~/bin"   →  Load migration-scripts.md
User does same task twice               →  Proactively suggest dr script

Discovery Before Creation (MANDATORY)

NEVER create a script without checking first:

# Step 1: ALWAYS run this first
dr -l/L                    # List ALL scripts with descriptions

# Step 2: Narrow search if needed
dr -l/L <folder>/        # e.g., dr -L git/
dr help <script-name>    # Verify script purpose

Discovery Decision Tree

User requests script → Run dr -L → Similar exists?
                                   ├── YES → Use or extend existing
                                   └── NO  → Create new with dr set

Discovery Outcomes

ALWAYS report discovery results to user.

Quick Reference

Core Commands

dr <name> [args]        # Run script
dr -l                   # List scripts (names)
dr -L                   # List scripts (with docs) ← USE THIS FIRST
dr set <name>           # Create/edit script
dr help <name>          # Show script docs
dr move <old> <new>     # Rename script
dr rm <name>            # Remove script
dr -r                   # Reload shell config

Aliases (-a)

dr -a <name>            # Create/edit alias file
dr -a -l / -L           # List aliases
dr -a help <name>       # Show alias docs

Configs (-c)

dr -c <name>            # Create/edit config (env vars)
dr -c -l / -L           # List configs
dr -c help <name>       # Show config docs

Collections (-col)

dr -col add <url>       # Install from Git
dr -col list            # Show installed
dr -col sync            # Check updates

Script Organization & Naming

Folder Taxonomy

Naming Rules

Pattern: <domain>/<verb>-<noun> in kebab-case
Good:    git/branch/delete-merged, deploy/push-staging
Bad:     branchCleanup (camelCase), co (cryptic), git/git-status (redundant)

Pre-Creation Checklist

Before dr set <name>:

1. Ran dr -L | grep <keyword> – no duplicates
2. Name uses kebab-case
3. Name is descriptive (not abbreviated)
4. Correct folder category
5. No collision: dr help <name> returns “not found”

Script Template

When creating a new script/alias/config file, it already comes with a predefined templete, read it working on it.

AI Decision Matrix

CREATE a dr script when:

DON’T create a script when:

• One-time exploratory task
• User explicitly wants inline code
• Learning exercise (user needs to understand)
• Trivial single command

Prompt Templates

When user asks for information:

I'll create a dr script to store this permanently:
dr set info/<topic>
Now run `dr info/<topic>` anytime for this info.

When user asks for a workflow:

Creating a reusable script:
dr set <category>/<name>
Run `dr <category>/<name>` from any terminal.

Proactive suggestion (same task twice):

Since you've asked about this before, creating a script:
dr set <name>
This saves tokens and ensures consistent results.

Reference Routing

MANDATORY References – Load ENTIRE file before proceeding:

On-Demand References – Load specific sections:

Do NOT Load:

• architecture.md for normal script creation
• Multiple migration files simultaneously
• commands.md when Quick Reference suffices

File Locations

Anti-Patterns (NEVER Do)

Script Creation

• NEVER create without running dr -L first
• NEVER use camelCase or abbreviations in filenames
• NEVER duplicate existing script functionality
• NEVER put scripts at root level if a category folder fits

General

• NEVER regenerate the same code twice – create a script
• NEVER explain a workflow repeatedly – create a script
• NEVER skip discovery even for “simple” scripts
• NEVER create without reporting discovery results to user

Helper System

Scripts can load reusable modules, they are located in ~/.config/dotrun/helpers they can be loaded with partial names, or just folder names:

[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"
loadHelpers global/colors   # Load by path
loadHelpers my-collection  # Load all from collection

there are all valid imports for the following file: .../helpers/git/pull-requests/getdiffs.sh

loadHelpers git                        # will load all `helpers/**/git/**/*.sh` or `helpers/**/git.sh`
loadHelpers git/pull-requests          # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers pull-requests              # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers git/pull-requests/getdiffs # will load all `helpers/**/git/pull-requests/getdiffs/**/*.sh` or `helpers/**/git/pull-requests/getdiffs.sh`
loadHelpers getdiffs                   # will load all `helpers/**/getdiffs/**/*.sh` or `helpers/**/getdiffs.sh`

Collections for Team Sharing

dr -col add https://github.com/team/scripts.git
dr -col sync   # Check for updates
dr -col update <name>

Pro Tips

1. Organize: dr set git/cleanup, dr set docker/build
2. Load order: 01-paths.config before 02-api.config
3. Document: DOC blocks power dr help and dr -L
4. Reload: dr -r after config changes
5. Verify: dr help <name> before running unknown scripts