Installation Guide

This guide covers installing rstbuddy on different platforms and systems.

Prerequisites

System Requirements

Python 3.10 or higher
pip, pipx, or uv package manager
Internet connection for package downloads

Optional Dependencies

Pandoc: Required only for AI summarization feature
OpenAI API Key: Required only for AI summarization feature

Installation Methods

Using uv (Recommended)

uv is a fast Python package installer and resolver.

Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install rstbuddy:

# Install globally
uv tool install rstbuddy

# Verify installation
rstbuddy --version

Using pipx

pipx installs Python applications in isolated environments.

Install pipx:

# macOS
brew install pipx
pipx ensurepath

# Ubuntu/Debian
sudo apt update
sudo apt install pipx
pipx ensurepath

# Windows
python -m pip install --user pipx
python -m pipx ensurepath

Install rstbuddy:

# Install globally
pipx install rstbuddy

# Verify installation
rstbuddy --version

Using pip

Standard pip installation (not recommended for command-line tools).

Install rstbuddy:

# Install globally (requires sudo on Unix-like systems)
pip install rstbuddy

# Install for current user only
pip install --user rstbuddy

# Verify installation
rstbuddy --version

From Source

Build and install from the source code.

Clone and Install:

# Clone the repository
git clone https://github.com/your-org/rstbuddy.git
cd rstbuddy

# Install in development mode
uv sync
uv run pip install -e .

# Or using pip
pip install -e .

Verification

After installation, verify that rstbuddy is working correctly:

# Check version
rstbuddy --version

# Show help
rstbuddy --help

# Show settings
rstbuddy settings

Expected output for version command:

┌─────────────────────────────────────────────────────────────────┐
│                      rstbuddy Version Info                      │
├─────────────────────────────────────────────────────────────────┤
│ Package    │ Version                                            │
├─────────────────────────────────────────────────────────────────┤
│ rstbuddy   │ 0.1.0                                              │
│ click      │ 8.1.7                                              │
│ rich       │ 13.7.0                                             │
└─────────────────────────────────────────────────────────────────┘

Optional Dependencies

Pandoc Installation

Required only for the AI summarization feature.

macOS:

# Using Homebrew
brew install pandoc

# Verify installation
pandoc --version

Ubuntu/Debian:

# Using apt
sudo apt update
sudo apt install pandoc

# Verify installation
pandoc --version

Windows:

Download installer from https://pandoc.org/installing.html
Run the installer and follow the prompts
Restart your terminal after installation

Verify Pandoc:

# Check if pandoc is available
pandoc --version

# Check if it's in PATH
which pandoc  # Unix-like systems
where pandoc  # Windows

OpenAI API Key Setup

Required only for the AI summarization feature.

Get API Key:

Sign up at https://platform.openai.com/
Navigate to API Keys section
Create a new API key
Copy the key (starts with “sk-“)

Configure API Key:

# Set as environment variable
export RSTBUDDY_OPENAI_API_KEY="sk-your-actual-api-key-here"

# Or add to configuration file
echo 'openai_api_key = "sk-your-actual-api-key-here"' >> ~/.config/.rstbuddy.toml

Verify Configuration:

# Check if API key is loaded
rstbuddy settings | grep openai_api_key

Platform-Specific Instructions

macOS

Using Homebrew:

# Install Python if needed
brew install python@3.11

# Install rstbuddy
brew install rstbuddy

# Or use uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install rstbuddy

Using MacPorts:

# Install Python if needed
sudo port install python311

# Install rstbuddy
sudo port install rstbuddy

Linux (Ubuntu/Debian)

System Packages:

# Update package list
sudo apt update

# Install Python if needed
sudo apt install python3 python3-pip python3-venv

# Install rstbuddy
pip3 install --user rstbuddy

# Add to PATH if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Using uv (Recommended):

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Install rstbuddy
uv tool install rstbuddy

Linux (CentOS/RHEL/Fedora)

Using dnf/yum:

# Install Python if needed
sudo dnf install python3 python3-pip

# Install rstbuddy
pip3 install --user rstbuddy

Using uv (Recommended):

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install rstbuddy
uv tool install rstbuddy

Windows

Using pip:

# Install Python from https://python.org
# Ensure "Add Python to PATH" is checked during installation

# Open Command Prompt or PowerShell
pip install rstbuddy

# Verify installation
rstbuddy --version

Using uv (Recommended):

# Install uv using PowerShell
irm https://astral.sh/uv/install.ps1 | iex

# Restart PowerShell, then install rstbuddy
uv tool install rstbuddy

Using Chocolatey:

# Install Chocolatey first, then:
choco install rstbuddy

Using Scoop:

# Install Scoop first, then:
scoop install rstbuddy

Troubleshooting

Installation Issues

“command not found” after installation:

# Check if rstbuddy is in PATH
which rstbuddy

# Check installation location
pip show rstbuddy

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

Permission denied errors:

# Install for current user only
pip install --user rstbuddy

# Or use virtual environment
python -m venv rstbuddy-env
source rstbuddy-env/bin/activate
pip install rstbuddy

Python version issues:

# Check Python version
python3 --version

# Ensure Python 3.10+ is installed
# Use pyenv or similar to manage Python versions

Package conflicts:

# Use virtual environment
python -m venv rstbuddy-env
source rstbuddy-env/bin/activate
pip install rstbuddy

# Or use uv for better dependency resolution
uv tool install rstbuddy

Verification Issues

Version command fails:

# Check if rstbuddy is properly installed
pip list | grep rstbuddy

# Try running with Python module syntax
python -m rstbuddy --version

# Check for import errors
python -c "import rstbuddy; print(rstbuddy.__version__)"

Settings command fails:

# Check configuration file permissions
ls -la ~/.config/.rstbuddy.toml

# Try with verbose output
rstbuddy --verbose settings

# Check for configuration errors
rstbuddy --config-file /dev/null settings

Getting Help

If you encounter installation issues:

Check Prerequisites: Ensure Python 3.10+ is installed
Verify PATH: Ensure installation directory is in your PATH
Check Permissions: Ensure you have write permissions for installation
Use Virtual Environment: Isolate dependencies to avoid conflicts
Try Alternative Methods: Use uv or pipx instead of pip
Report Issues: Open an issue on GitHub with detailed error information

Useful Commands:

# Check Python version
python3 --version

# Check pip version
pip --version

# Check PATH
echo $PATH

# Check installation location
pip show rstbuddy

# Check for conflicts
pip check