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:

User Intent	dr Command	Check First
Create/run bash script	`dr set <name>` / `dr <name>`	`dr -l/L`
Shell alias/shortcut	`dr -a <name>`	`dr -a -l/L`
Environment variable/PATH	`dr -c <name>`	`dr -c -l/L`
Migrate shell config	See migration refs	-
Repetitive workflow	`dr set <category>/<name>`	`dr -l/L`

Trigger Detection

code

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:

bash

# 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

code

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

Discovery Outcomes

Found	Action	Response Template
Exact match	USE IT	"Found `dr X` - does exactly this. Running it now."
Similar script	EXTEND IT	"Found `dr X` which is close. Adding the feature."
No match	CREATE NEW	"Checked `dr -L` - nothing exists. Creating `dr set X`."

ALWAYS report discovery results to user.

Quick Reference

Core Commands

bash

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`)

bash

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

Configs (`-c`)

bash

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

Collections (`-col`)

bash

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

Script Organization & Naming

Folder Taxonomy

Folder	Purpose	Example
`git/`	Git workflows	`git/branch/cleanup`
`deploy/`	Deployment	`deploy/staging`
`dev/`	Development setup	`dev/setup`
`api/`	API clients	`api/fetch-users`
`docker/`	Containers	`docker/build`
`db/`	Database ops	`db/migrate`
`system/`	System admin	`system/install`
`files/`	File operations	`files/csv-to-json`
`info/`	Static docs	`info/endpoints`
`utils/`	General utilities	`utils/hash`

Naming Rules

code

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>:

• Ran dr -L | grep <keyword> - no duplicates
• Name uses kebab-case
• Name is descriptive (not abbreviated)
• Correct folder category
• 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:

Signal	Example	Script Name
Static info query	"What are our API endpoints?"	`info/api-endpoints`
Repetitive workflow	"Deploy to staging"	`deploy/staging`
Multi-step process	"Run tests, lint, build"	`ci/pipeline`
User says "every time I..."	Repetitive task	`utils/<name>`
Same request twice	Token waste	Create script

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:

code

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:

code

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

Proactive suggestion (same task twice):

code

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:

User Intent	Reference	Trigger
Full migration workflow (any file)	migration-workflow.md	"migrate file", "import into dotrun"
Migrate `.bashrc`, `.zshrc`, aliases	migration-shell-config.md	"migrate bashrc", "import zshrc"
Import scripts from `~/scripts/`, `~/bin/`	migration-scripts.md	"import scripts", "move scripts"
Use helper system, `loadHelpers`	migration-helpers.md	"helper", "shared functions", "loadHelpers"

On-Demand References - Load specific sections:

Need	Reference	When
Complete command syntax	commands.md	Quick Reference insufficient
File format specs	migration-formats.md	Creating files, need exact format
System architecture	architecture.md	Debugging, explaining internals

Do NOT Load:

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

File Locations

Type	Location	Extension
Scripts	`~/.config/dotrun/scripts/`	`.sh`
Aliases	`~/.config/dotrun/aliases/`	`.aliases`
Configs	`~/.config/dotrun/configs/`	`.config`
Helpers	`~/.config/dotrun/helpers/`	`.sh`

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:

bash

[[ -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

bash

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

bash

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

Pro Tips

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

DotRun CLI (dr) - Script Management Framework

Decision Routing Matrix

Trigger Detection

Discovery Before Creation (MANDATORY)

Discovery Decision Tree

Discovery Outcomes

Quick Reference

Core Commands

Aliases (-a)

Configs (-c)

Collections (-col)

Script Organization & Naming

Folder Taxonomy

Naming Rules

Pre-Creation Checklist

Script Template

AI Decision Matrix

CREATE a dr script when:

DON'T create a script when:

Prompt Templates

When user asks for information:

When user asks for a workflow:

Proactive suggestion (same task twice):

Reference Routing

MANDATORY References - Load ENTIRE file before proceeding:

On-Demand References - Load specific sections:

Do NOT Load:

File Locations

Anti-Patterns (NEVER Do)

Script Creation

General

Helper System

Collections for Team Sharing

Pro Tips

DotRun CLI (`dr`) - Script Management Framework

Aliases (`-a`)

Configs (`-c`)

Collections (`-col`)