dr-cli

name	dr-cli
description	Master the DotRun CLI for unified script, alias, and config management
metadata	{"mandatory-triggers":["User mentions script, bash, shell automation, or reusable commands","User mentions aliases, shortcuts, or command abbreviations","User mentions environment variables, PATH, exports, or shell config","User says \"automate\", \"workflow\", \"pipeline\", or \"repetitive task\"","User wants to create, run, list, or manage shell scripts","User mentions `.bashrc`, `.zshrc`, `config.fish`, or dotfiles migration","AI needs to automate a task that will be needed again - ALWAYS prefer dr scripts"],"trigger-keywords":"dr, dotrun, script, bash, shell, alias, config, export, PATH, automate, workflow, pipeline, migrate bashrc, import scripts","decision-rule":"If the task involves shell automation, scripts, aliases, or environment config - USE `dr` 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>:

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:

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

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