Installation Guide - jvPalma/dotrun GitHub Wiki

Installation Guide

← Back to README | Home | User Guide →

Table of Contents

🚀 Getting Started Path
Installation → User Guide → Script Development → Examples
Having issues? Check Troubleshooting or FAQ

Prerequisites

Before installing DotRun, ensure you have:

  • Operating System: Linux, macOS, or Windows (WSL)
  • Shell: Bash 4.0+, Zsh, or Fish
  • Git: Version 2.0 or higher (required)
  • curl or wget: For downloading the installer

Optional Dependencies

  • ShellCheck: For automatic script linting
  • glow: For rendering markdown documentation in terminal

Quick Install

Install DotRun with our automated installer:

# Using curl
bash <(curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh)

# Using wget
bash <(wget -qO- https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh)

The installer will:

  1. Download the dr script to ~/.local/bin/
  2. Create the workspace directory at ~/.config/dotrun/
  3. Initialize a Git repository for version control
  4. Set up shell completions for your current shell
  5. Add ~/.local/bin to your PATH if needed

Manual Installation

If you prefer manual installation:

# 1. Create directories
mkdir -p ~/.local/bin ~/.config/dotrun/{bin,docs,templates,collections}

# 2. Download the dr script
curl -o ~/.local/bin/dr https://raw.githubusercontent.com/jvPalma/dotrun/master/dr
chmod +x ~/.local/bin/dr

# 3. Initialize Git repository
cd ~/.config/dotrun && git init

# 4. Add ~/.local/bin to PATH (add to your shell rc file)
export PATH="$HOME/.local/bin:$PATH"

Shell Configuration

Bash

Add to ~/.bashrc:

# DotRun PATH
export PATH="$HOME/.local/bin:$PATH"

# Enable completions
source ~/.config/dotrun/completions/drun-completion.bash

Zsh

Add to ~/.zshrc:

# DotRun PATH
export PATH="$HOME/.local/bin:$PATH"

# Enable completions
source ~/.config/dotrun/completions/drun-completion.zsh

Fish

Add to ~/.config/fish/config.fish:

# DotRun PATH
set -gx PATH $HOME/.local/bin $PATH

# Completions are automatically loaded from ~/.config/fish/completions/

Verification

After installation, verify everything is working:

# Check version
dr --version

# List available scripts (should be empty initially)
dr -l

# Check installation paths
dr --info

# Test creating a script
dr set test
dr test
dr rm test

Customization

Custom Installation Directory

To install DotRun in a custom location:

DR_PREFIX=/custom/path ./install.sh

Environment Variables

You can customize DotRun behavior with these environment variables:

# Custom workspace directory (default: ~/.config/dotrun)
export DR_HOME=/path/to/workspace

# Default editor for script editing
export EDITOR=vim

# Disable automatic linting
export DR_NO_LINT=1

AI Agent Skill

Enhance your AI coding assistant with DotRun knowledge. The skill teaches AI agents how to create, manage, and migrate scripts following DotRun best practices.

Claude Code

# Install via npx (recommended)
npx skills add jvPalma/dotrun

Other AI Tools

For GitHub Copilot, Cursor, Gemini, and other AI tools, see the skill installation guide.

Troubleshooting

Common Issues

Command not found: drun

  • Ensure ~/.local/bin is in your PATH
  • Reload your shell configuration: source ~/.bashrc (or equivalent)

Permission denied

  • Make sure the dr script is executable: chmod +x ~/.local/bin/dr

Git not initialized

  • Run cd ~/.config/dotrun && git init

Shell completions not working

  • Ensure completion files exist in ~/.config/dotrun/completions/
  • Check that your shell rc file sources the completion script

Getting Help

Next Steps

Now that DotRun is installed:

  1. Learn the Basics: Continue to the User Guide
  2. Create Your First Script: Follow the Quick Start Tutorial
  3. Explore Examples: Check out Example Scripts
  4. Set Up Team Sharing: Learn about Collections

← Back to README | User Guide → | Top ↑