Installation Guide¶

This comprehensive guide covers all the ways to install Perspt on your system, from simple binary downloads to building from source.

System Requirements¶

Minimum Requirements¶

Component	Requirement
Operating System	Linux, macOS, Windows 10+
Architecture	x86_64, ARM64 (Apple Silicon)
Memory	50MB RAM minimum
Storage	10MB disk space
Terminal	Any terminal with UTF-8 support
Network	Internet connection for AI API calls

Recommended Requirements¶

Component	Recommendation
Terminal	Modern terminal with 256+ colors and Unicode support
Font	Monospace font with good Unicode coverage (e.g., Fira Code, JetBrains Mono)
Shell	Bash, Zsh, Fish, or PowerShell
Memory	100MB+ RAM for optimal performance

Quick Install¶

Choose your preferred installation method:

Download pre-built binaries for immediate use:

Linux x86_64:

curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-linux-x86_64.tar.gz | tar xz
chmod +x perspt
sudo mv perspt /usr/local/bin/

macOS (Intel):

curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-darwin-x86_64.tar.gz | tar xz
chmod +x perspt
sudo mv perspt /usr/local/bin/

macOS (Apple Silicon):

curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-darwin-arm64.tar.gz | tar xz
chmod +x perspt
sudo mv perspt /usr/local/bin/

Windows:

# Download from GitHub releases page
# Extract perspt.exe and add to PATH

Install using Rust’s package manager:

# Install from crates.io
cargo install perspt

# Or install the latest development version
cargo install --git https://github.com/eonseed/perspt

Build the latest version from source:

# Clone repository
git clone https://github.com/eonseed/perspt.git
cd perspt

# Build release version
cargo build --release

# Install to cargo bin
cargo install --path .

Package Managers¶

Homebrew (macOS/Linux)¶

# Add tap (when available)
brew tap eonseed/perspt

# Install
brew install perspt

# Update
brew upgrade perspt

Scoop (Windows)¶

# Add bucket (when available)
scoop bucket add perspt https://github.com/eonseed/scoop-perspt

# Install
scoop install perspt

# Update
scoop update perspt

Chocolatey (Windows)¶

# Install (when available)
choco install perspt

# Update
choco upgrade perspt

APT (Debian/Ubuntu)¶

# Add repository (when available)
curl -fsSL https://releases.perspt.dev/gpg | sudo gpg --dearmor -o /usr/share/keyrings/perspt.gpg
echo "deb [signed-by=/usr/share/keyrings/perspt.gpg] https://releases.perspt.dev/apt stable main" | sudo tee /etc/apt/sources.list.d/perspt.list

# Install
sudo apt update
sudo apt install perspt

RPM (Red Hat/Fedora)¶

# Add repository (when available)
sudo dnf config-manager --add-repo https://releases.perspt.dev/rpm/perspt.repo

# Install
sudo dnf install perspt

Building from Source¶

Prerequisites¶

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Clone and Build¶

# Clone the repository
git clone https://github.com/eonseed/perspt.git
cd perspt

# Build in release mode
cargo build --release

# The binary will be in target/release/perspt
./target/release/perspt --version

Install System-Wide¶

# Option 1: Using cargo install
cargo install --path .

# Option 2: Manual installation
sudo cp target/release/perspt /usr/local/bin/
sudo chmod +x /usr/local/bin/perspt

# Option 3: User-local installation
mkdir -p ~/.local/bin
cp target/release/perspt ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Development Build¶

For development and testing:

# Clone with all development tools
git clone https://github.com/eonseed/perspt.git
cd perspt

# Install development dependencies
cargo install cargo-watch cargo-edit

# Build in debug mode
cargo build

# Run tests
cargo test

# Run with hot reload during development
cargo watch -x run

Docker Installation¶

Run Perspt in a Docker container:

Basic Usage¶

# Pull the image
docker pull ghcr.io/eonseed/perspt:latest

# Run interactively
docker run -it --rm \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/eonseed/perspt:latest

With Configuration¶

# Create a config directory
mkdir -p ~/.config/perspt

# Create your config.json
cat > ~/.config/perspt/config.json << EOF
{
  "api_key": "your-api-key-here",
  "default_model": "gpt-4o-mini",
  "default_provider": "openai"
}
EOF

# Run with mounted config
docker run -it --rm \
  -v ~/.config/perspt:/app/config \
  ghcr.io/eonseed/perspt:latest \
  --config /app/config/config.json

Docker Compose¶

Create a docker-compose.yml file:

version: '3.8'
services:
  perspt:
    image: ghcr.io/eonseed/perspt:latest
    stdin_open: true
    tty: true
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./config:/app/config
    command: ["--config", "/app/config/config.json"]

Run with:

docker-compose run --rm perspt

Platform-Specific Instructions¶

Linux¶

Ubuntu/Debian:

# Update package list
sudo apt update

# Install dependencies for building (if building from source)
sudo apt install build-essential curl git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install Perspt
cargo install perspt

Arch Linux:

# Install from AUR (when available)
yay -S perspt

# Or build from source
sudo pacman -S rust git
git clone https://github.com/eonseed/perspt.git
cd perspt
cargo build --release

CentOS/RHEL/Fedora:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install development tools
sudo dnf groupinstall "Development Tools"
sudo dnf install git

# Install Perspt
cargo install perspt

macOS¶

Using Homebrew (Recommended):

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Rust
brew install rust

# Install Perspt
cargo install perspt

Using MacPorts:

# Install Rust
sudo port install rust

# Install Perspt
cargo install perspt

Manual Installation:

# Install Xcode command line tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install Perspt
cargo install perspt

Windows¶

Using Chocolatey:

# Install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Rust
choco install rust

# Install Perspt
cargo install perspt

Using Scoop:

# Install Scoop
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# Install Rust
scoop install rust

# Install Perspt
cargo install perspt

Manual Installation:

Download and install Rust from rustup.rs
Open Command Prompt or PowerShell
Run: cargo install perspt

Verification¶

After installation, verify that Perspt is working correctly:

# Check version
perspt --version

# Check help
perspt --help

# Test basic functionality (requires API key)
export OPENAI_API_KEY="your-key-here"
perspt --model-name gpt-4o-mini

You should see output similar to:

perspt 0.4.0
Your Terminal's Window to the AI World

Updating Perspt¶

Cargo Installation¶

# Update to latest version
cargo install perspt --force

# Or update all cargo packages
cargo install-update -a

Binary Installation¶

# Download and replace binary
curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-linux-x86_64.tar.gz | tar xz
sudo mv perspt /usr/local/bin/

Package Managers¶

# Homebrew
brew upgrade perspt

# APT
sudo apt update && sudo apt upgrade perspt

# DNF
sudo dnf upgrade perspt

# Chocolatey
choco upgrade perspt

# Scoop
scoop update perspt

Uninstallation¶

Cargo Installation¶

# Uninstall using cargo
cargo uninstall perspt

Manual Binary¶

# Remove binary
sudo rm /usr/local/bin/perspt

# Remove configuration (optional)
rm -rf ~/.config/perspt

Package Managers¶

# Homebrew
brew uninstall perspt

# APT
sudo apt remove perspt

# DNF
sudo dnf remove perspt

# Chocolatey
choco uninstall perspt

# Scoop
scoop uninstall perspt

Troubleshooting¶

Common Issues¶

“Command not found” error:

# Check if cargo bin is in PATH
echo $PATH | grep -q "$HOME/.cargo/bin" && echo "Cargo bin in PATH" || echo "Cargo bin NOT in PATH"

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

Permission denied:

# Make sure the binary is executable
chmod +x /usr/local/bin/perspt

# Or use without sudo
mkdir -p ~/.local/bin
cp perspt ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Build failures:

# Update Rust toolchain
rustup update

# Clear cargo cache
cargo clean

# Rebuild
cargo build --release

Missing dependencies on Linux:

# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# CentOS/RHEL/Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install pkgconfig openssl-devel

Getting Help¶

If you encounter issues during installation:

Check the GitHub Issues: Issues Page
Join the Discussion: GitHub Discussions
Read the FAQ: Troubleshooting
Contact Support: Create a new issue with: - Your operating system and version - Rust version (rustc --version) - Installation method used - Complete error message

Next Steps¶

After successful installation:

Set up API keys: Configuration Guide
Learn basic usage: Getting Started
Explore features: User Guide
Join the community: GitHub Discussions