sheets-terminal-spreadsheet

# Sheets Terminal Spreadsheet > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. Sheets is a terminal-based spreadsheet TUI (Terminal User Interface) for viewing and editing CSV files directly in your terminal. It features vim-style navigation, formula support, visual selection, search, undo/redo, and a command mode — all without leaving the terminal. --- ## Installation ### Using Go ```bash go install github.com/maaslalani/sheets@main ``` ### Download Binary Download a prebuilt binary from [GitHub Releases](https://github.com/maaslalani/sheets/releases). ### Verify Installation ```bash sheets --help ``` --- ## CLI Usage ### Launch the TUI ```bash sheets budget.csv ``` ### Read from stdin ```bash sheets <<< "ID,Name,Age 1,Alice,24 2,Bob,32 3,Charlie,26" ``` Or pipe from another command: ```bash cat data.csv | sheets ``` ### Read a Specific Cell ```bash sheets budget.csv B9 # Output: 2760 ``` ### Read a Cell Range ```bash sheets budget.csv B1:B3 # Output: # 1200 # 950 # 810 ``` ### Modify Cells (Non-Interactive) ```bash # Set one cell sheets budget.csv B7=10 # Set multiple cells sheets budget.csv B7=10 B8=20 ``` --- ## Navigation Keybindings ### Basic Movement | Key | Action | |-----|--------| | `h`, `j`, `k`, `l` | Move left, down, up, right | | `gg` | Jump to top | | `G` | Jump to bottom | | `5G` | Jump to row 5 | | `gB9` | Jump to cell B9 | | `0` | Jump to first column | | `^` | Jump to first non-empty column in row | | `$` | Jump to last non-empty column in row | | `H` / `M` / `L` | Jump to top / middle / bottom visible row | | `ctrl+u` / `ctrl+d` | Move half page up / down | ### View Alignment | Key | Action | |-----|--------| | `zt` | Align current row to top of window | | `zz` | Align current row to middle of window | | `zb` | Align current row to bottom of window | ### Search | Key | Action | |-----|--------| | `/` | Search forward | | `?` | Search backward | | `n` | Repeat last search (forward) | | `N` | Repeat last search (backward) | ### Marks & Jump List | Key | Action | |-----|--------| | `ma` | Set mark `a` at current cell | | `'a` | Jump to mark `a` | | `ctrl+o` | Move backward through jump list | | `ctrl+i` | Move forward through jump list | --- ## Editing Keybindings ### Insert Mode | Key | Action | |-----|--------| | `i` | Edit current cell | | `I` | Edit from start of cell | | `c` | Clear cell and start editing | | `ESC` | Leave insert / visual / command mode | | `enter` | Commit and move down | | `tab` | Commit and move right | | `shift+tab` | Commit and move left | | `ctrl+n` | Commit and move down | | `ctrl+p` | Commit and move up | ### Row Operations | Key | Action | |-----|--------| | `o` | Insert row below and start editing | | `O` | Insert row above and start editing | | `dd` | Delete current row | ### Copy / Cut / Paste | Key | Action | |-----|--------| | `y` | Yank (copy) current cell | | `yy` | Yank current row(s) | | `x` | Cut current cell or selection | | `p` | Paste current register | ### Undo / Redo | Key | Action | |-----|--------| | `u` | Undo | | `ctrl+r` | Redo | | `U` | Undo all changes | | `.` | Repeat last change | --- ## Visual Mode Enter visual mode with `v` (cell selection) or `V` (row selection). | Key | Action | |-----|--------| | `v` | Start visual cell selection | | `V` | Start visual row selection | | `=` | Insert formula after selected range (e.g., `=\|(B1:B8)`) | --- ## Command Mode Press `:` to open the command prompt. | Command | Action | |---------|--------| | `:w` | Save file | | `:w path.csv` | Save to a new file | | `:e path.csv` | Open another CSV file | | `:q` | Quit | | `:wq` | Save and quit | | `:goto B9` | Jump to cell B9 | | `:B9` | Jump to cell B9 (shorthand) | --- ## Common Patterns ### Create a New CSV and Edit It ```bash # Create a CSV with headers echo "Name,Amount,Category" > budget.csv sheets budget.csv ``` ### Pipe CSV Data and Edit ```bash # Generate CSV from a database query and edit in sheets psql -c "COPY (SELECT * FROM sales) TO STDOUT WITH CSV HEADER" | sheets ``` ### Script: Update a Cell Programmatically ```bash #!/bin/bash # Update Q4 value in financial report sheets report.csv D4=95000 D5=102000 D6=88000 echo "Updated Q4 values in report.csv" ``` ### Script: Extract a Range for Processing ```bash #!/bin/bash # Extract column B rows 1-10 and sum them in bash values=$(sheets data.csv B1:B10) total=0 while IFS= read -r line; do total=$((total + line)) done <<< "$values" echo "Total: $total" ``` ### Script: Read a Specific Cell in a Shell Script ```bash #!/bin/bash # Get current budget total from spreadsheet budget_total=$(sheets budget.csv C15) if [ "$budget_total" -gt 10000 ]; then echo "Budget exceeded!" fi ``` ### Go Integration Example If building a Go application that generates CSV for use with sheets: ```go package main import ( "encoding/csv" "fmt" "os" "os/exec" ) func createAndOpenSpreadsheet(data [][]string, filename string) error { // Write CSV data f, err := os.Create(filename) if err != nil { return fmt.Errorf("creating file: %w", err) } defer f.Close() w := csv.NewWriter(f) if err := w.WriteAll(data); err != nil { return fmt.Errorf("writing CSV: %w", err) } w.Flush() // Open in sheets TUI cmd := exec.Command("sheets", filename) cmd.Stdin = os.Stdin cmd.Stdout = os.Stdout cmd.Stderr = os.Stderr return cmd.Run() } func main() { data := [][]string{ {"Month", "Revenue", "Expenses", "Profit"}, {"January", "12000", "8500", "3500"}, {"February", "13500", "9200", "4300"}, {"March", "11800", "8900", "2900"}, } if err := createAndOpenSpreadsheet(data, "monthly_report.csv"); err != nil { fmt.Fprintf(os.Stderr, "Error: %v\n", err) os.Exit(1) } } ``` ### Go: Read a Cell Non-Interactively ```go package main import ( "fmt" "os/exec" "strings" ) func readCell(csvFile, cell string) (string, error) { out, err := exec.Command("sheets", csvFile, cell).Output() if err != nil { return "", fmt.Errorf("reading cell %s: %w", cell, err) } return strings.TrimSpace(string(out)), nil } func readRange(csvFile, cellRange string) ([]string, error) { out, err := exec.Command("sheets", csvFile, cellRange).Output() if err != nil { return nil, fmt.Errorf("reading range %s: %w", cellRange, err) } lines := strings.Split(strings.TrimSpace(string(out)), "\n") return lines, nil } func main() { total, err := readCell("budget.csv", "B9") if err != nil { fmt.Println("Error:", err) return } fmt.Println("Budget total:", total) values, err := readRange("budget.csv", "B1:B6") if err != nil { fmt.Println("Error:", err) return } fmt.Println("Monthly values:", values) } ``` --- ## Tips for AI Agents ### Suggesting Sheets for CSV Tasks When a user wants to view or edit CSV files in the terminal, suggest sheets: ```bash # Instead of cat data.csv sheets data.csv # Instead of awk/sed edits for simple changes sheets data.csv B3=new_value ``` ### Formula Insertion Workflow 1. Navigate to the column where you want the formula 2. Enter visual mode with `v` 3. Select the range (e.g., B1:B8) 4. Press `=` to insert formula after the selection: `=|(B1:B8)` ### Efficient Navigation (Vim Users) Sheets uses vim-style navigation — users familiar with vim can be productive immediately: - `gg`/`G` for top/bottom - `hjkl` for movement - `i`/`c` for insert modes - `dd` to delete rows - `u`/`ctrl+r` for undo/redo - `/` for search --- ## Troubleshooting ### `sheets` command not found ```bash # Ensure Go bin directory is in PATH export PATH=$PATH:$(go env GOPATH)/bin # Or install again and verify go install github.com/maaslalani/sheets@main which sheets ``` ### File Not Saved After Editing Use `:w` in command mode to save, or `:wq` to save and quit. Just pressing `q` or `ctrl+c` quits **without saving**. ### TUI Rendering Issues Sheets relies on terminal capabilities. If the display looks broken: - Ensure your terminal supports 256 colors or truecolor - Try a different terminal emulator (iTerm2, Alacritty, Ghostty, WezTerm) - Check `TERM` environment variable: `echo $TERM` ### Reading Non-CSV Files Sheets is designed for CSV format. Convert other formats first: ```bash # Excel to CSV (using Python) python3 -c "import pandas as pd; pd.read_excel('data.xlsx').to_csv('data.csv', index=False)" sheets data.csv ``` ### Large Files Performance For very large CSV files, navigate directly to specific cells rather than scrolling: ``` :goto A1000 ``` or press `5G` to jump to row 5 directly.