Skip to content

INSTALL.md

Latest commit

 

History

History
289 lines (207 loc) · 6.24 KB

INSTALL.md

File metadata and controls

289 lines (207 loc) · 6.24 KB

Installation Guide

This guide covers various installation methods for mailcli on different platforms.

System Requirements

  • Go: 1.24 or later (if building from source)
  • OS: Linux, macOS, or Windows
  • Network: Internet connection for IMAP servers
  • Disk: ~10 MB for binary

Installation Methods

Method 1: Pre-built Binary (Recommended)

Download the pre-built binary for your platform from GitHub Releases.

Linux

# Linux (amd64) - Auto-detect latest version
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
wget https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-linux-amd64.tar.gz
tar -xzf mailcli-linux-amd64.tar.gz
mkdir -p ~/.local/bin
mv mailcli-linux-amd64 ~/.local/bin/mailcli

# Linux (arm64)
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
wget https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-linux-arm64.tar.gz
tar -xzf mailcli-linux-arm64.tar.gz
mkdir -p ~/.local/bin
mv mailcli-linux-arm64 ~/.local/bin/mailcli

Note: If ~/.local/bin is not in your PATH:

# For Linux (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS

# macOS (Intel)
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
curl -L https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-darwin-amd64.tar.gz -o mailcli.tar.gz
tar -xzf mailcli.tar.gz
mkdir -p ~/.local/bin
mv mailcli-darwin-amd64 ~/.local/bin/mailcli

# macOS (Apple Silicon)
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
curl -L https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-darwin-arm64.tar.gz -o mailcli.tar.gz
tar -xzf mailcli.tar.gz
mkdir -p ~/.local/bin
mv mailcli-darwin-arm64 ~/.local/bin/mailcli

Note: macOS users need to add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows

# Windows (PowerShell)
$version = (Invoke-RestMethod https://api.github.com/repos/keepmind9/mailcli/releases/latest).tag_name
Invoke-WebRequest -Uri "https://github.com/keepmind9/mailcli/releases/download/$version/mailcli-windows-amd64.zip" -OutFile "mailcli.zip"
Expand-Archive -Path mailcli.zip -DestinationPath .
Move-Item mailcli-windows-amd64.exe C:\Tools\mailcli.exe

Method 2: Build from Source

If you have Go installed, you can build mailcli from source.

Install Go

macOS (using Homebrew):

brew install go

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install golang-go

Verify Go installation:

go version
# Expected: go version go1.24.x or later

Clone and Build

# Clone repository
git clone https://github.com/keepmind9/mailcli.git
cd mailcli

# Install dependencies
go mod download

# Build
make build

# Binary will be at ./bin/mailcli
./bin/mailcli version

Install to System Path

# Copy binary to user directory (recommended)
mkdir -p ~/.local/bin
cp bin/mailcli ~/.local/bin/

# Or install to system path (requires sudo)
sudo cp bin/mailcli /usr/local/bin/

# Verify
mailcli version

Method 3: Using go install

If you have Go 1.24+, you can install directly:

go install github.com/keepmind9/mailcli/cmd/mailcli@latest

The binary will be installed to ~/go/bin/mailcli. Make sure ~/go/bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:~/go/bin

# Reload shell
source ~/.bashrc  # or source ~/.zshrc

# Verify
mailcli version

Post-Installation

Verify Installation

mailcli version
mailcli --help

Initialize Configuration

# Check if config exists
ls -la ~/.config/mailcli/

# If not exists, initialize
mailcli config add

Test Connection

# Test your configured account
mailcli config test

Upgrade

From Pre-built Binary

# Download latest version
VERSION=$(curl -s https://api.github.com/repos/keepmind9/mailcli/releases/latest | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
wget https://github.com/keepmind9/mailcli/releases/download/$VERSION/mailcli-linux-amd64.tar.gz
tar -xzf mailcli-linux-amd64.tar.gz
mv mailcli-linux-amd64 ~/.local/bin/mailcli

# Verify
mailcli version

From Source

# Pull latest changes
cd mailcli
git pull origin main

# Rebuild
make build

# Reinstall
cp bin/mailcli ~/.local/bin/

Using go install

go install github.com/keepmind9/mailcli/cmd/mailcli@latest

Uninstallation

Remove Binary

# If installed to user directory
rm ~/.local/bin/mailcli

# Or if installed to system path
sudo rm /usr/local/bin/mailcli

# Or if installed via go install
rm ~/go/bin/mailcli

Remove Configuration

# Remove config directory
rm -rf ~/.config/mailcli/

Troubleshooting

"command not found: mailcli"

Problem: The binary is not in your PATH.

Solution:

  1. Check where mailcli is installed: which mailcli
  2. Add to PATH if needed: 
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # macOS
  3. Reload shell: source ~/.bashrc or source ~/.zshrc

"permission denied"

Problem: The binary is not executable.

Solution:

chmod +x ~/.local/bin/mailcli

"go: command not found"

Problem: Go is not installed or not in PATH.

Solution:

  1. Install Go from https://golang.org/dl/
  2. Or use package manager: brew install go (macOS) or sudo apt install golang-go (Linux)

Build fails with "go: module ... not found"

Problem: Go modules not cached or network issue.

Solution:

# Set Go proxy if in China
export GOPROXY=https://goproxy.cn,direct

# Try again
go mod download
make build

Next Steps

After installation:

  1. Initialize configuration: mailcli config add
  2. Read usage guide: USAGE.md
  3. Check examples: README.md