# Installation Guide

[← Back to README](../../README.md) | [Home](Home.md) | [User Guide →](User-Guide.md)

---

## Table of Contents

- [Prerequisites](#prerequisites)
- [Quick Install](#quick-install)
- [Manual Installation](#manual-installation)
- [Shell Configuration](#shell-configuration)
- [Verification](#verification)
- [Customization](#customization)
- [AI Agent Skill](#ai-agent-skill)
- [Troubleshooting](#troubleshooting)
- [Next Steps](#next-steps)

> **🚀 Getting Started Path**  
> **Installation** → [User Guide](User-Guide.md) → [Script Development](Script-Development.md) → [Examples](Script-Examples.md)  
> Having issues? Check [Troubleshooting](Troubleshooting.md) or [FAQ](FAQ.md)

## 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:

```bash
# 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:

```bash
# 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`:

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

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

### Zsh

Add to `~/.zshrc`:

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

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

### Fish

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

```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:

```bash
# 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:

```bash
DR_PREFIX=/custom/path ./install.sh
```

### Environment Variables

You can customize DotRun behavior with these environment variables:

```bash
# 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

```bash
# 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](https://github.com/jvPalma/dotrun/tree/master/skills/dr-cli#installation).

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

- Check the [FAQ](FAQ.md)
- View [Troubleshooting Guide](Troubleshooting.md)
- Report issues on [GitHub](https://github.com/jvPalma/dotrun/issues)

## Next Steps

Now that DotRun is installed:

1. **Learn the Basics**: Continue to the [User Guide](User-Guide.md)
2. **Create Your First Script**: Follow the [Quick Start Tutorial](User-Guide.md#quick-start-tutorial)
3. **Explore Examples**: Check out [Example Scripts](Script-Examples.md)
4. **Set Up Team Sharing**: Learn about [Collections](Team-Workflows.md#collections-management)

---

[← Back to README](../../README.md) | [User Guide →](User-Guide.md) | [Top ↑](#installation-guide)