Quick Start Tutorial

Quick Start Tutorial

Skill Level: Beginner • Time: 5 minutes

Get up and running with DotRun in about 5 minutes. This tutorial walks you through installation, creating your first script, and understanding the core workflow.

Prerequisites

• Operating System: Linux, macOS, or Windows (WSL)
• Shell: Bash 4.0+, Zsh, or Fish
• Required: Git (for version control)
• Recommended: A text editor you're comfortable with

Step 1: Installation (1 minute)

One-Command Install

curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh

What this does:

• Downloads DotRun to ~/.config/dotrun
• Installs the dr command to your PATH
• Sets up shell completion
• Creates initial directory structure

Verify Installation

# Check version
dr --version

# List available example scripts
dr -l

# Get help
dr --help

Expected output:

DotRun v3.1.0
Available scripts:
  ai/gpt
  git/branchCleanup
  examples/hello-world

Set Your Editor (Optional)

# Set your preferred editor
export EDITOR="code" # VS Code
export EDITOR="vim"  # Vim
export EDITOR="nano" # Nano

# Make it permanent
echo 'export EDITOR="code"' >>~/.bashrc

Step 2: Your First Script (2 minutes)

Create a Simple Script

# Create your first script (opens in your editor)
dr set hello

This opens your editor with a template. Replace the content with:

#!/usr/bin/env bash
### DOC
# A friendly greeting script
# Usage: dr hello [name]
### DOC
set -euo pipefail

main() {
  local name="${1:-World}"
  echo "👋 Hello, $name!"
  echo "🎉 Your first DotRun script is working!"
}

main "$@"

Save and exit your editor.

Run Your Script

# Run without arguments
dr hello

# Run with a name
dr hello "Developer"

Expected output:

👋 Hello, Developer!
🎉 Your first DotRun script is working!

View and Edit Documentation

# Show inline documentation
dr help hello

# Edit the script again (works for both create and modify)
dr set hello

Step 3: Organize Your Scripts (1 minute)

Create Organized Scripts

# Create scripts in categories
dr set git/quick-status
dr set docker/cleanup
dr set utils/backup-home

Add Useful Content

Let's make the git script actually useful:

# Edit the git status script
dr set git/quick-status

Add this content:

#!/usr/bin/env bash
### DOC
# Quick git status with branch info and stash count
# Shows clean status with colors and helpful info
### DOC
set -euo pipefail

main() {
  if ! git rev-parse --git-dir >/dev/null 2>&1; then
    echo "❌ Not in a git repository"
    exit 1
  fi

  local branch=$(git branch --show-current)
  local stash_count=$(git stash list | wc -l)
  local status=$(git status --porcelain)

  echo "🌿 Branch: $branch"
  echo "📦 Stashed changes: $stash_count"

  if [[ -z "$status" ]]; then
    echo "✅ Working directory clean"
  else
    echo "📝 Uncommitted changes:"
    git status --short
  fi
}

main "$@"

Test Your Organized Script

# Run from any git repository
cd ~/projects/some-repo
dr git/quick-status

List Your Scripts

# Simple list
dr -l

# Detailed list with descriptions
dr -L

Step 4: Team Collaboration (1 minute)

Import a Team Collection

# Import DotRun's example collection
dr import https://github.com/jvPalma/dotrun.git examples

# List all collections
dr collections list

# Use a script from the collection
dr examples/git/branchCleanup

Create Your Own Collection

# Create a new collection directory
mkdir ~/my-team-scripts
cd ~/my-team-scripts

# Initialize as a git repository
git init
git remote add origin git@github.com:yourteam/scripts.git

# Export your personal scripts to share
dr export ~/.config/dotrun/bin ./shared-scripts

# Commit and push
git add .
git commit -m "Initial team scripts collection"
git push -u origin main

Share Your Collection

Team members can now import your collection:

dr import git@github.com:yourteam/scripts.git team-tools

Advanced Features (Optional)

Move and Rename Scripts

# Rename a script (preserves documentation)
dr move hello utils/greeting

# Reorganize scripts
dr move git/quick-status git/status-enhanced

# Run the moved script
dr utils/greeting "Team"

Set Up Shell Completion

If completion wasn't set up automatically:

# For Bash - add to ~/.bashrc
echo 'source ~/.config/dotrun/dr_completion.bash' >>~/.bashrc

# For Zsh - add to ~/.zshrc
echo 'source ~/.config/dotrun/dr_completion.zsh' >>~/.zshrc

# For Fish
cp ~/.config/dotrun/dr_completion.fish ~/.config/fish/completions/dr.fish

# Reload your shell
source ~/.bashrc # or exec $SHELL

Test completion:

dr <TAB><TAB>          # Shows available scripts
dr git/<TAB><TAB>      # Shows git category scripts
dr set <TAB><TAB>      # Shows scripts to edit

Install AI Agent Skill (Bonus)

If you use Claude Code or other AI coding assistants, install the DotRun skill for smarter script creation:

# For Claude Code
npx skills add jvPalma/dotrun

This teaches AI agents to create properly structured scripts, use helpers, and follow DotRun conventions.

Next Steps

For Individual Developers

1. Create Daily Workflow Scripts:

   dr set dev/start-project
   dr set deploy/staging
   dr set testing/run-all

2. Integrate with Your Dotfiles:

   # If using yadm
   dr yadm-init
   
   # Manual integration
   ln -s ~/.config/dotrun ~/dotfiles/dotrun

3. Explore Examples:

   dr -L                         # See all available scripts
   dr examples/ai/gpt .          # AI code analysis
   dr examples/git/branchCleanup # Git branch cleanup

For Teams

1. Set Up Team Collection:

   • Create a shared repository
   • Export common scripts
   • Document team conventions

2. Establish Workflow:

   • Regular script updates
   • Code review for shared scripts
   • Documentation standards

3. Advanced Collaboration:

   • Multiple collections for different teams
   • Script namespacing strategies
   • Version management

Common Issues & Solutions

dr: command not found

Solution: Ensure ~/.local/bin is in your PATH:

export PATH="$PATH:~/.local/bin"
echo 'export PATH="$PATH:~/.local/bin"' >>~/.bashrc

Scripts won't execute

Solution: Check permissions:

chmod +x ~/.config/dotrun/bin/your-script.sh

Can't edit scripts

Solution: Set your EDITOR variable:

export EDITOR="nano" # or your preferred editor

Tab completion not working

Solution: Restart your shell or source the completion:

source ~/.config/dotrun/dr_completion.bash
# or exec $SHELL

Summary

In this tutorial, you've:

✅ Installed DotRun with shell completion ✅ Created your first script with documentation ✅ Organized scripts into logical categories ✅ Set up team collaboration with collections ✅ Learned advanced features like move/rename

You now have:

• A working DotRun v3.1.0 installation
• Personal scripts organized in categories
• Understanding of team collaboration workflow
• Foundation for building complex automation

What's Next?

• Script Development Best Practices - Learn professional scripting patterns
• Team Collaboration Best Practices - Deep dive into team workflows
• Advanced Script Patterns - Complex automation techniques
• Workflow Recipes - See real-world examples
• API Reference - Complete command documentation

Happy scripting! 🚀

---

This tutorial should take about 5 minutes to complete. If you run into issues, check the Troubleshooting Guide or create an issue.