Troubleshooting

Common issues and solutions for pair-cli installation and usage.

Installation Issues

Permission Errors

Problem: npm install -g @pair/pair-cli fails with permission errors.

Solution: Use a Node version manager or install locally.

# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 18
nvm use 18
 
# Option 2: Install locally in project
pnpm add -D @foomakers/pair-cli
# Use with: pnpm dlx pair-cli
 
# Option 3: Use sudo (not recommended)
sudo npm install -g @pair/pair-cli

Command Not Found

Problem: pair-cli command not found after installation.

Solutions:

# Check PATH
echo $PATH
which pair-cli
 
# If using nvm, ensure Node version is active
nvm current
nvm use 18
 
# Restart terminal or source profile
source ~/.bashrc  # or ~/.zshrc
 
# For local install, use npx
npx pair-cli --version

Node.js Version Issues

Problem: Errors about unsupported Node version.

Solution: Ensure Node 18+ is active.

# Check version
node --version  # Should be 18.0.0 or higher
 
# Update with nvm
nvm install 18
nvm use 18
nvm alias default 18

Runtime Issues

Target Directory Permissions

Problem: pair-cli install fails with "permission denied".

Solution: Ensure write access to target directory.

# Check permissions
ls -la .
 
# Fix permissions if needed
chmod 755 .
 
# Or run in a directory you own
mkdir ~/my-project
cd ~/my-project
pair-cli install

Network/Proxy Issues

Problem: Installation fails due to network restrictions.

Solutions:

# Use manual install for offline environments
# Download from: https://github.com/foomakers/pair/releases
# Extract and run directly
 
# Configure npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
 
# Or use manual install

Platform-Specific Issues

macOS

Problem: "command not found" after global install.

Solution: Check PATH and npm prefix.

# Check npm global install location
npm config get prefix
 
# Ensure it's in PATH
export PATH="$(npm config get prefix)/bin:$PATH"
 
# Add to ~/.zshrc or ~/.bashrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

Linux

Problem: Native module compilation fails.

Solution: Install build tools.

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential python3-dev
 
# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install python3-devel

Windows

Problem: Line ending or path issues.

Solutions:

# Use Git Bash or WSL
# Ensure Node is in PATH
where node
 
# Use manual install with .cmd files
# Download pair-cli-manual-vX.Y.Z.zip
# Run pair-cli.cmd instead of pair-cli

Verification Issues

Assets Not Installing

Problem: pair-cli install runs but no files are created.

Solutions:

# Check current directory
pwd
 
# Ensure you have write permissions
touch test.txt && rm test.txt
 
# Try with debug-level logging (if available)
pair-cli install --log-level debug
 
# Check if assets are available
pair-cli install --list-targets

Outdated Assets

Problem: Installed assets seem outdated.

Solution: Update to latest version.

# Update all assets
pair-cli update
 
# Or reinstall
pair-cli install --force  # if available

Getting Help

Diagnostic Information

When reporting issues, include:

# System info
uname -a
node --version
npm --version
pnpm --version
 
# pair-cli info
pair-cli --version
 
# Installation method
which pair-cli
npm list -g @pair/pair-cli

Support Channels

Documentation: Check this guide and the Installation FAQ
Issues: File bugs at GitHub Issues
Discussions: Ask questions in GitHub Discussions

Quick Fixes

Issue	Quick Fix
Permission denied	`chmod 755 .` or use `sudo`
Command not found	`npx pair-cli` or check PATH
Node version	`nvm use 18`
Network blocked	Use manual install
Files not created	Check directory permissions

Prevention

Always use Node 18+ with pnpm
Install globally with nvm, locally with pnpm dlx
Test in a clean directory first
Keep pair-cli updated: npm update -g @pair/pair-cli

Troubleshooting

On this page