Skip to content

INSTALL.md

Latest commit

 

History

History
336 lines (229 loc) · 6.12 KB

INSTALL.md

File metadata and controls

336 lines (229 loc) · 6.12 KB
Raw

Installation Guide

This document provides detailed installation instructions for Excel TUI on various platforms.

Table of Contents

Requirements

  • Go 1.21 or higher (for building from source)
  • Terminal with 256-color support
  • For Linux: xclip or xsel for clipboard support

Quick Install

Using go install

go install github.com/SreeAditya-Dev/Cello-TUI@latest

Download Pre-built Binaries

  1. Visit the releases page
  2. Download the appropriate binary for your platform
  3. Extract and move to your PATH

Platform-Specific Instructions

macOS

Using Homebrew (Recommended)

# Coming soon
brew install cello

Manual Installation

# Download latest release
curl -L https://github.com/SreeAditya-Dev/Cello-TUI/releases/latest/download/cello-darwin-arm64.tar.gz -o cello-tui.tar.gz

# Extract
tar xzf cello-tui.tar.gz

# Make executable
chmod +x cello-darwin-arm64

# Move to PATH
sudo mv cello-darwin-arm64 /usr/local/bin/cello

# Verify
cello --version

Note: On macOS, you may need to allow the app in System Preferences → Security & Privacy

Linux

Using Package Manager

# Debian/Ubuntu (Coming soon)
sudo apt install cello

# Arch Linux (Coming soon)
yay -S cello

# Fedora (Coming soon)
sudo dnf install cello

Manual Installation

# Download latest release
wget https://github.com/SreeAditya-Dev/Cello-TUI/releases/latest/download/cello-linux-amd64.tar.gz

# Extract
tar xzf cello-linux-amd64.tar.gz

# Make executable
chmod +x cello-linux-amd64

# Move to PATH
sudo mv cello-linux-amd64 /usr/local/bin/cello

# Install clipboard utilities
sudo apt-get install xclip  # Ubuntu/Debian
# or
sudo pacman -S xclip        # Arch
# or
sudo dnf install xclip      # Fedora

# Verify
cello --version

Windows

Using Chocolatey (Coming soon)

choco install cello

Using Scoop (Coming soon)

scoop install cello

Manual Installation

  1. Download cellowindows-amd64.zip from releases
  2. Extract the ZIP file
  3. Add the directory to your PATH:
    • Right-click "This PC" → Properties
    • Advanced system settings → Environment Variables
    • Edit PATH and add the directory
  4. Open a new terminal and verify: cello --version

Recommended Terminal: Windows Terminal for best experience

Building from Source

Prerequisites

# Install Go (if not already installed)
# Visit: https://golang.org/doc/install

# Verify Go installation
go version

Build Steps

# Clone the repository
git clone https://github.com/SreeAditya-Dev/Cello-TUI.git
cd cello

# Install dependencies
go mod download

# Build
go build -o cello .

# Or use Make
make build

# Install globally
make install

Development Build

# Build with race detector
go build -race -o cello .

# Run tests
make test

# Run with coverage
make test-coverage

Verifying Installation

After installation, verify it works:

# Check version
cello --version

# Run with sample data
cello sample_data.csv

# Test with a theme
cello sample_data.csv --theme nord

Troubleshooting

"command not found"

Problem: Shell can't find the cello command

Solution:

# Check if binary is in PATH
which cello

# If not found, add to PATH
export PATH="$PATH:/path/to/cello"

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$PATH:/path/to/cello"' >> ~/.bashrc

Clipboard Not Working (Linux)

Problem: Copy operations don't work

Solution:

# Install clipboard utilities
sudo apt-get install xclip xsel  # Ubuntu/Debian
sudo pacman -S xclip xsel        # Arch
sudo dnf install xclip xsel      # Fedora

Colors Not Displaying Correctly

Problem: Terminal shows wrong colors or no colors

Solution:

# Check TERM variable
echo $TERM

# Should be xterm-256color or similar
# Set it if needed
export TERM=xterm-256color

# Make permanent
echo 'export TERM=xterm-256color' >> ~/.bashrc

"Permission Denied" on macOS

Problem: macOS blocks execution of downloaded binary

Solution:

# Remove quarantine attribute
xattr -d com.apple.quarantine /path/to/cello

# Or allow in System Preferences
# System Preferences → Security & Privacy → General

Go Build Fails

Problem: Build errors or dependency issues

Solution:

# Clean and retry
go clean -cache -modcache
go mod download
go mod verify
go build .

Large Files Load Slowly

Problem: Excel files with 50k+ rows are slow

Solution:

  • This is expected for very large files
  • The app uses lazy loading for optimal performance
  • Consider filtering/splitting the data beforehand
  • Use CSV format when possible (faster than Excel)

Uninstalling

If installed via go install

rm $(which cello)

If installed manually

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

# Remove config (if any)
rm -rf ~/.config/cello

If installed via package manager

# macOS
brew uninstall cello

# Linux
sudo apt remove cello     # Debian/Ubuntu
yay -R cello              # Arch
sudo dnf remove cello     # Fedora

# Windows
choco uninstall cello     # Chocolatey
scoop uninstall cello     # Scoop

Next Steps

After successful installation:

  1. Read the README for feature overview
  2. Check CONTRIBUTING if you want to contribute
  3. Report issues on GitHub

Support

If you encounter issues not covered here:

  • Check existing issues
  • Create a new issue with:
    • Your OS and version
    • Go version (if building from source)
    • Terminal emulator
    • Error messages
    • Steps to reproduce

Happy viewing! 📊✨