Skip to content

Installation Guide

This guide covers all methods for installing Zorac.

The easiest way to install Zorac on macOS or Linux:

# Add the tap
brew tap chris-colinsky/zorac

# Install
brew install zorac

# Verify installation
zorac --help

Upgrading

brew upgrade zorac

Uninstalling

brew uninstall zorac

pipx installs Python applications in isolated environments, preventing dependency conflicts:

# Install pipx if you don't have it
brew install pipx       # macOS/Linux
# or: pip install pipx  # Any platform

# Install zorac
pipx install zorac

# Verify installation
zorac --help

Upgrading

pipx upgrade zorac

Uninstalling

pipx uninstall zorac

pip (All Platforms)

Standard Python package installation:

# Install
pip install zorac

# Verify installation
zorac --help

Upgrading

pip install --upgrade zorac

Uninstalling

pip uninstall zorac

uv (For Developers)

Using the modern uv package manager:

# Install globally
uv tool install zorac

# Or run without installing (ephemeral)
uvx zorac

# Verify installation
zorac --help

Upgrading

uv tool upgrade zorac

Uninstalling

uv tool uninstall zorac

From Source (Development)

For contributing or development:

# Clone the repository
git clone https://github.com/chris-colinsky/zorac.git
cd zorac

# Install dependencies
uv sync

# Run from source
uv run zorac

# Or activate venv and run directly
source .venv/bin/activate
zorac

See Development Guide for more details on contributing.

Windows Users

Zorac runs on Windows via WSL (Windows Subsystem for Linux):

  1. Install WSL: wsl --install
  2. Open your Linux distribution
  3. Follow the pip or pipx installation instructions above

Verification

After installation, verify Zorac is working:

zorac --help

On first run, Zorac will guide you through configuration.

Data Directory

Zorac stores all user data in ~/.zorac/:

File Purpose
config.json Server URL, model, and settings
session.json Conversation history
history Command-line history

To completely remove Zorac and its data:

# Uninstall (use your installation method)
pipx uninstall zorac   # or pip, brew, etc.

# Remove data
rm -rf ~/.zorac

Next Steps

After installation: