Developer Experience

← Team Workflows | Home | Configuration Management →

Overview

DotRun is designed with developer experience in mind:

Shell Completions: Tab completion for all commands
Editor Support: Integration with popular editors
Automatic Validation: ShellCheck linting on save
Smart Features: Aliases, shortcuts, and productivity tools
Customizable: Adapt to your workflow

Shell Completions

Bash Completion

Enable tab completion in Bash:

# Add to ~/.bashrc
source ~/.config/dotrun/completions/drun-completion.bash

# Features:
# - Script name completion
# - Category completion
# - Option completion
# - Subcommand completion

Usage examples:

dr <TAB>                 # List all scripts
dr git/<TAB>             # List scripts in git category
dr deploy/prod<TAB>      # Complete to deploy/production
dr --<TAB>               # List all options

Zsh Completion

This section documents the DotRun v3.1.0 Zsh completion experience. It's designed to make script discovery and management fast and predictable through a two-tier, namespace-based model with intuitive color cues and consistent navigation.

Overview: Two-tier namespace-based system

Tier 1 (Primary): Optimized for running scripts quickly. You get folders, scripts, and a small set of special commands. No noise.
Tier 2 (Namespaced Management): Organized by command type. Use flags or subcommands to access management commands for scripts, aliases, config, and collections.

This makes "run things" the default and "manage things" discoverable but out of your way.

Tier 1 — Primary (Script Execution)

When you type dr <TAB>, completion shows:

Folders: yellow, with a trailing slash to indicate deeper navigation
Scripts: cyan, no .sh extension
Special commands: green (help, -l, -L, -h, --help)
Hint: dark gray (a discoverability nudge for Tier 2)

Example (visual — comments indicate colors):

# dr <TAB>

apps/                                                       # yellow (fg=33) folder
services/                                                   # yellow (fg=33) folder
deploy                                                      # cyan   (fg=36) script (no .sh)
test                                                        # cyan   (fg=36) script (no .sh)
help                                                        # green  (fg=32) special
-l                                                          # green  (fg=32) special (list)
-L                                                          # green  (fg=32) special (list:details)
-h                                                          # green  (fg=32) special (help)
--help                                                      # green  (fg=32) special (help)
(hint: -s/scripts, -a/aliases, -c/config, -col/collections) # dark gray (fg=90)

Notes:

Trailing slash "/" means you can keep navigating into folders.
Scripts appear without ".sh" to keep the surface clean.
Special commands are always visible; they don't pollute script listings.

Real-world usage examples:

# List available scripts quickly
dr -l

# Get details (e.g., descriptions) for scripts
dr -L

# Run a script at a path
dr apps/backend/build

# Navigate into a folder and discover scripts
dr services/<TAB>
# services/:
# api/         # yellow
# payments/    # yellow
# migrate      # cyan
# restart      # cyan

Tier 2 — Namespaced Management

Tier 2 groups management operations by type. You can enter Tier 2 with either flags or subcommands (dual interface).

Scripts: dr -s <TAB> or dr scripts <TAB>
- set, move, rename, docs
- Colored green (fg=32) because they are management commands closely tied to execution
Aliases: dr -a <TAB> or dr aliases <TAB>
- set, list, remove, reload
- Colored purple (fg=35)
Config: dr -c <TAB> or dr config <TAB>
- set, get, list, edit, unset, reload
- Colored red (fg=31)
Collections: dr -col <TAB> or dr collections <TAB>
- add, list, list:details, sync, update
- Uses default completion color in v3.1.0 (no dedicated color)

Examples (visual):

# Scripts namespace
dr -s <TAB>
# add     # green  (fg=32)
# edit    # green  (fg=32)
# move    # green  (fg=32)
# rename  # green  (fg=32)
# list    # green  (fg=32)
# help    # green  (fg=32)

# Aliases namespace
dr aliases <TAB>
# init    # purple (fg=35)
# add     # purple (fg=35)
# list    # purple (fg=35)
# edit    # purple (fg=35)
# remove  # purple (fg=35)
# reload  # purple (fg=35)

# Config namespace
dr -c <TAB>
# init    # red    (fg=31)
# set     # red    (fg=31)
# get     # red    (fg=31)
# list    # red    (fg=31)
# edit    # red    (fg=31)
# unset   # red    (fg=31)
# reload  # red    (fg=31)

# Collections namespace
dr -col <TAB>
# list
# list:details
# remove

Real-world flows:

# Add a new script, then open it in your editor
dr -s set build

# Move / rename scripts
dr scripts move old/path/build new/path/build
dr scripts rename old-name new-name

# Initialize and manage aliases
dr -a init
dr aliases add deploy "dr services/api/deploy"
dr -a list
dr -a edit deploy

# Configure defaults and reload
dr -c init
dr -c set default_env production
dr -c get default_env
dr -c reload

# Explore and prune collections
dr collections list
dr collections list:details
dr collections remove legacy-set

Color scheme

DotRun v3.1.0 completion uses the following colors consistently:

Green (fg=32): Special + Script management
Yellow (fg=33): Folders with trailing slash "/"
Cyan (fg=36): Scripts without ".sh"
Purple (fg=35): Alias commands
Red (fg=31): Config commands
Dark Gray (fg=90): Hint text

Visual reference:

# Green   (fg=32)  -> help, -l, -L, -h, --help; scripts namespace management
# Yellow  (fg=33)  -> apps/, services/, ...
# Cyan    (fg=36)  -> deploy, test, build, migrate, ...
# Purple  (fg=35)  -> aliases: add, edit, remove, reload, ...
# Red     (fg=31)  -> config: set, get, list, edit, ...
# DarkGray(fg=90)  -> (hint: -s/scripts, -a/aliases, -c/config, -col/collections)

Hierarchical navigation

Directories are navigable, and completion keeps you oriented:

# Discover top-level content
dr <TAB>
# apps/   services/   deploy   test   help   -l   -L   -h   --help
# (hint: -s/scripts, -a/aliases, -c/config, -col/collections)

# Dive into services/
dr services/<TAB>
# api/   payments/   migrate   restart

# One more level
dr services/api/<TAB>
# seed  migrate  start  stop

# Run immediately once discovered
dr services/api/start

Key behaviors:

Trailing slash "/" indicates more levels.
Scripts always appear extensionless.
Completion is context-aware: once you're inside a folder, only valid children appear.

Dual interface (flags vs subcommands)

DotRun supports both short/long flag style and subcommand style for Tier 2. Choose what fits your workflow.

Parity mappings:

Scripts: -s == scripts
Aliases: -a == aliases
Config: -c == config
Collections: -col == collections

Equivalent examples:

dr -s set build
dr scripts set build

dr -a list
dr aliases list

dr -c set default_env production
dr config set default_env production

dr -col list:details
dr collections list:details

Guidance:

Flags are compact and fast for habitual users.
Subcommands are explicit and self-documenting for teams and new contributors.

Customization (advanced users)

Zsh completion is highly configurable. Below are safe, optional tweaks that play nicely with DotRun's UX.

Enable menu selection and richer matching:

# ~/.zshrc
autoload -Uz compinit
compinit
zmodload zsh/complist

# Arrow-key menu selection
zstyle ':completion:*' menu select

# Case-insensitive + smart separators (., _, -) matching
zstyle ':completion:*' matcher-list \
  'm:{a-z}={A-Z}' \
  'r:|[._-]=* r:|=*'

# Group results by type and show descriptions with subtle formatting
zstyle ':completion:*' group-name ''
zstyle ':completion:*:descriptions' format '%F{yellow}-- %d --%f'

Optional: Adjust list colors to align with your terminal theme:

# Example: retain clear grouping without overpowering your theme
# (Leave DotRun's semantic colors intact; this only affects general list rendering.)
zstyle ':completion:*' list-colors ''

Shell aliases for personal ergonomics:

# Prefer flags
alias drs='dr -s'
alias dra='dr -a'
alias drc='dr -c'
alias drcol='dr -col'

# Or prefer subcommands
alias drs='dr scripts'
alias dra='dr aliases'
alias drc='dr config'
alias drcol='dr collections'

Note:

We recommend keeping DotRun's semantic color scheme; the above zstyles are optional quality-of-life improvements.
If you use a completion framework (Oh My Zsh, zinit, etc.), put these after its initialization so they aren't overridden.

Comparison with other shells

Bash
- Pros: Ubiquitous; basic completion support.
- Cons: Less expressive UI (no menu-select by default), weaker hint/description formatting, limited colorization vs Zsh.
- Recommendation: Works, but Zsh provides a better, more discoverable UX for DotRun v3.1.0.
Fish
- Pros: Very user-friendly suggestions and inline hints.
- Cons: Different completion model; requires a separate completion script. Color semantics may not match Zsh exactly.
- Recommendation: Good experience, but Zsh remains the reference implementation for DotRun's namespace UI and color semantics.

Tips and tricks (power users)

Type-ahead narrowing: Start typing path segments and use "/" to filter only folders, e.g., dr s/a/<TAB> to focus on services/api.
Rapid list + run: dr -L to recall details, then up-arrow and complete the script name.
Bulk rename with preview: Use dr -s list to confirm, then dr -s rename with completion to avoid typos.
Edit what you just ran: fc (Zsh's "fix command") pairs well if you ran dr -s edit and want to tweak.
Combine with fzf (optional): dr -l | fzf | xargs -I{} dr {} if you like fuzzy pickers outside of completion.
Partial separators: With the matcher-list above, dr srvapi mg can still complete to services/api/migrate.

Troubleshooting

Completions don't appear for dr
- Ensure compinit is initialized:
```
autoload -Uz compinit && compinit
```
- Restart shell or re-source config:
```
exec zsh
# or
source ~/.zshrc
```
- Check dr is on PATH:
```
command -v dr
```
Colors or descriptions look off
- Terminal must support ANSI colors; verify $TERM (e.g., xterm-256color).
- Remove conflicting zstyles and test again:
```
grep -n "zstyle" ~/.zshrc
```
- If using a theme/framework, ensure your zstyles load after it.
Tier 2 commands not showing
- Verify version:
```
dr --version # should be 3.1.0+
```
- Try a fresh compinit to clear stale caches:
```
rm -f ~/.zcompdump* && compinit
```
Hierarchical navigation missing trailing "/"
- Check that your completion isn't forcing file-like display overrides via list-colors.
- Test in a clean shell:
```
ZDOTDIR="$(mktemp -d)" zsh -f
autoload -Uz compinit && compinit
# then try `dr <TAB>` again
```
Conflicts with other completion systems
- Ensure only one completion provider initializes for dr. If multiple frameworks are installed, prefer a single source of compinit.
- Confirm the completion function is discoverable:
```
# Commonly the function is named `_dr` in $fpath
print -l $fpath | while read -r p; do [[ -f "$p/_dr" ]] && echo "$p/_dr"; done
```
Nothing completes inside a folder that you know exists
- Confirm the folder exists in your scripts root and has read permissions.
- If your repo changed, reload your environment or run rehash:
```
rehash
```

Fish Completion

Fish shell automatic completion:

# Completions auto-loaded from:
# ~/.config/fish/completions/dr.fish

# Features:
# - Real-time suggestions
# - Syntax highlighting
# - Description preview

Fish usage:

dr <TAB>                 # Visual completion menu
dr --help<TAB>           # Shows option description
dr deploy/<TAB>          # Category-aware completion

Custom Completions

Add custom completion logic:

# In completion file
_dr_custom_complete() {
  local cur="${COMP_WORDS[COMP_CWORD]}"

  # Add dynamic completions
  if [[ "$cur" == "project:"* ]]; then
    COMPREPLY=($(compgen -W "$(ls ~/projects)" -- "${cur#project:}"))
  fi
}

Editor Integration

VS Code

Create VS Code tasks:

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "DotRun: List Scripts",
      "type": "shell",
      "command": "dr -L",
      "problemMatcher": []
    },
    {
      "label": "DotRun: Run Script",
      "type": "shell",
      "command": "dr ${input:scriptName}",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "scriptName",
      "type": "promptString",
      "description": "Script name to run"
    }
  ]
}

VS Code snippets:

// snippets/dotrun.json
{
  "DotRun Script": {
    "prefix": "dr-script",
    "body": [
      "#!/usr/bin/env bash",
      "### DOC",
      "# ${1:Script Name} - ${2:Brief description}",
      "#",
      "# ${3:Detailed description}",
      "#",
      "# Usage: dr ${TM_FILENAME_BASE} ${4:[options]}",
      "#",
      "# Examples:",
      "#   dr ${TM_FILENAME_BASE}",
      "### DOC",
      "",
      "set -euo pipefail",
      "",
      "$0"
    ]
  }
}

Vim/Neovim

Vim integration:

" ~/.vimrc or ~/.config/nvim/init.vim

" Run current script with DotRun
nnoremap <leader>dr :!dr %:t:r<CR>

" Edit DotRun script
command! -nargs=1 DRunEdit :e ~/.config/dotrun/bin/<args>

" List DotRun scripts
command! DRunList :!dr -L

" Create new script
function! DRunNew(name)
    execute '!dr set ' . a:name
    execute 'e ~/.config/dotrun/bin/' . a:name
endfunction
command! -nargs=1 DRunNew :call DRunNew(<q-args>)

Emacs

Emacs configuration:

;; ~/.emacs.d/init.el

;; DotRun mode
(defun dr-run-script ()
  "Run current script with DotRun"
  (interactive)
  (shell-command
    (concat "dr " (file-name-base (buffer-file-name)))))

(defun dr-list-scripts ()
  "List all DotRun scripts"
  (interactive)
  (shell-command "dr -L"))

;; Keybindings
(global-set-key (kbd "C-c d r") 'dr-run-script)
(global-set-key (kbd "C-c d l") 'dr-list-scripts)

Automatic Linting

ShellCheck Integration

DotRun automatically runs ShellCheck:

# Automatic linting on:
dr set newscript # After creation/editing
dr lint          # Manual lint all scripts

Configure linting:

# Disable linting
export DR_NO_LINT=1

# Custom ShellCheck options
export SHELLCHECK_OPTS="-e SC2034 -e SC2154"

# Lint specific severity
export DR_LINT_LEVEL="error" # error, warning, info, style

Custom Linters

Add custom validation:

# ~/.config/dotrun/hooks/pre-save
#!/usr/bin/env bash

# Check for common issues
check_script() {
  local script="$1"

  # Must have documentation
  if ! grep -q "^### DOC" "$script"; then
    echo "Error: Missing ### DOC section"
    return 1
  fi

  # Check for hardcoded paths
  if grep -q "/home/$(whoami)" "$script"; then
    echo "Warning: Hardcoded home path detected"
  fi

  # Verify shebang
  if ! head -1 "$script" | grep -q "^#!/usr/bin/env"; then
    echo "Warning: Use #!/usr/bin/env for portability"
  fi
}

check_script "$1"

Smart Aliases

Alias Management

DotRun includes alias management:

# Add alias
dr alias add gc "git commit -m"

# List aliases
dr alias list

# Remove alias
dr alias rm gc

# Export aliases
dr alias export >~/.aliases

Category-based Aliases

Organize aliases by category:

# Git aliases
dr alias add git/st "git status"
dr alias add git/co "git checkout"
dr alias add git/cm "git commit -m"

# Docker aliases
dr alias add docker/ps "docker ps --format 'table {{.Names}}\t{{.Status}}'"
dr alias add docker/clean "docker system prune -af"

# List by category
dr alias list git/

Smart Alias Features

Advanced alias capabilities:

# Aliases with functions
dr alias add mkcd 'f() { mkdir -p "$1" && cd "$1"; }; f'

# Aliases with completion
dr alias add proj 'cd ~/projects/$1' --complete-dirs

# Conditional aliases
dr alias add update 'if [[ "$OSTYPE" == "darwin"* ]]; then brew update; else sudo apt update; fi'

Productivity Features

Quick Commands

Built-in productivity commands:

# Quick navigation
dr cd git  # cd ~/.config/dotrun/bin/git
dr cd docs # cd ~/.config/dotrun/docs

# Quick creation
dr quick deploy-fix # Create and edit immediately

# Batch operations
dr lint --all # Lint all scripts
dr test --all # Run all test scripts

Script Templates

Use templates for common patterns:

# List templates
dr template list

# Create from template
dr set api/newservice --template=rest-api

# Create custom template
dr template create mytemplate

# Share templates
dr template export mytemplate >mytemplate.sh

Workflow Automation

Automate common workflows:

# Git workflow
dr workflow git-feature "feature-name"
# Creates branch, sets up PR template, etc.

# Release workflow
dr workflow release "1.2.3"
# Tags, builds, deploys, notifies

# Daily workflow
dr workflow daily
# Updates repos, cleans temp files, backs up

Integration Hooks

Hook into DotRun events:

# ~/.config/dotrun/hooks/post-add
#!/usr/bin/env bash
# Run after adding new script

script="$1"
echo "New script created: $script"

# Auto-commit
cd ~/.config/dotrun
git add "bin/$script"
git commit -m "Add: $script"

# Notify team
slack-notify "#dev-scripts" "New script added: $script"

Customization

Configuration File

Create a DotRun configuration:

# ~/.config/dotrun/config
DR_DEFAULT_EDITOR="code"
DR_DEFAULT_SHELL="bash"
DR_COMPLETION_STYLE="verbose"
DR_LINT_ON_SAVE=true
DR_AUTO_COMMIT=true
DR_TEMPLATE_DIR="$HOME/.config/dotrun/my-templates"

Custom Commands

Add custom subcommands:

# ~/.config/dotrun/commands/stats
#!/usr/bin/env bash
# Show script statistics

echo "DotRun Statistics:"
echo "=================="
echo "Total scripts: $(find ~/.config/dotrun/bin -type f | wc -l)"
echo "Categories: $(find ~/.config/dotrun/bin -type d -mindepth 1 | wc -l)"
echo "Documentation: $(find ~/.config/dotrun/docs -name "*.md" | wc -l)"

# Make executable
chmod +x ~/.config/dotrun/commands/stats

# Use: dr stats

Themes and Colors

Customize output colors:

# ~/.config/dotrun/theme
DR_COLOR_SUCCESS="32"  # Green
DR_COLOR_ERROR="31"    # Red
DR_COLOR_WARNING="33"  # Yellow
DR_COLOR_INFO="34"     # Blue
DR_COLOR_HEADER="35"   # Magenta
DR_COLOR_CATEGORY="36" # Cyan

# Unicode symbols
DR_SYMBOL_SUCCESS="✓"
DR_SYMBOL_ERROR="✗"
DR_SYMBOL_WARNING="⚠"
DR_SYMBOL_INFO="ℹ"

Plugins

Create DotRun plugins:

# ~/.config/dotrun/plugins/git-integration.sh

# Auto-detect git repos
dr_git_detect() {
  if [[ -d .git ]]; then
    export DR_GIT_REPO=$(basename "$PWD")
    export DR_GIT_BRANCH=$(git branch --show-current)
  fi
}

# Add to prompt
PROMPT_COMMAND="dr_git_detect; $PROMPT_COMMAND"

# Context-aware scripts
dr() {
  if [[ -n "$DR_GIT_REPO" && "$1" == "commit" ]]; then
    command dr git/quick-commit "${@:2}"
  else
    command dr "$@"
  fi
}

Next Steps

Enhance your DotRun experience:

Configure Environment: Set up Configuration Management
Manage Aliases: Learn Alias Management
Team Setup: Configure Team Collaboration
Browse Examples: See Example Scripts
Troubleshooting: Check Troubleshooting Guide

← Team Collaboration | Configuration Management → | Top ↑

Uh oh!

Developer Experience

Developer Experience

Table of Contents

Overview

Shell Completions

Bash Completion

Zsh Completion

Overview: Two-tier namespace-based system

Tier 1 — Primary (Script Execution)

Tier 2 — Namespaced Management

Color scheme

Hierarchical navigation

Dual interface (flags vs subcommands)

Customization (advanced users)

Comparison with other shells

Tips and tricks (power users)

Troubleshooting

Fish Completion

Custom Completions

Editor Integration

VS Code

Vim/Neovim

Emacs

Automatic Linting

ShellCheck Integration

Custom Linters

Smart Aliases

Alias Management

Category-based Aliases

Smart Alias Features

Productivity Features

Quick Commands

Script Templates

Workflow Automation

Integration Hooks

Customization

Configuration File

Custom Commands

Themes and Colors

Plugins

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!