dr-cli by jvpalma/dotrun

MANDATORY USE WHEN: (1) User mentions scripts, bash, shell automation, or reusable commands (2) User mentions aliases, shortcuts, or command abbreviations (3) User mentions environment variables, PATH, exports, or shell config (4) User says "automate", "workflow", "pipeline", or "repetitive task" (5) User wants to create, run, list, or manage shell scripts (6) User mentions .bashrc, .zshrc, config.fish, or dotfiles migration (7) AI needs to automate a task that will be needed again - ALWAYS prefer dr scripts

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

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

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

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

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

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:

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:

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:

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

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

dr-cli