Excel-CLI

A lightweight terminal-based Excel viewer with Vim-like navigation, it allows basic Excel file viewing and provides a simple way to export Excel data to JSON format.

Features

• Browse Excel worksheets
• Switch between sheets in multi-sheet workbooks
• Delete worksheets from multi-sheet workbooks
• Navigate through cells using Vim-like commands
• Edit cell contents
• Save changes to Excel files
• Export data to JSON format

Installation & Uninstallation

Installation

Option 1: Install from Cargo (Recommended)

The package is published to crates.io and can be installed directly using:

cargo install excel-cli

Option 2: Compile from Source

Requires Rust and Cargo. Install using the following commands:

# Clone the repository
git clone https://github.com/fuhan666/excel-cli.git
cd excel-cli
cargo build --release

# Install to system
cargo install --path .

Uninstallation

cargo uninstall excel-cli

Usage

# Open an Excel file in interactive mode
excel-cli path/to/your/file.xlsx

# Export all sheets to JSON and output to stdout (for piping)
excel-cli path/to/your/file.xlsx --json-export

# Export with custom header direction and count
excel-cli path/to/your/file.xlsx -j -d v -r 2

# Pipe JSON output to another command
excel-cli path/to/your/file.xlsx -j > data.json # (example) Save JSON output to a file

Command-line Options

• --json-export, -j: Export all sheets to JSON and output to stdout (for piping)
• --direction, -d: Header direction for JSON export: 'h' for horizontal (top rows), 'v' for vertical (left columns). Default: 'h'
• --header-count, -r: Number of header rows (for horizontal) or columns (for vertical) in JSON export. Default: 1

User Interface

The application has a simple and intuitive interface:

• Title Bar with Sheet Tabs: Displays the current file name and all available sheets with the current sheet highlighted
• Spreadsheet: The main area displaying the Excel data
• Status Bar: Shows current cell reference and available commands

Keyboard Shortcuts

• h, j, k, l or arrow keys: Move selection (1 cell)
• [: Switch to previous sheet (stops at first sheet)
• ]: Switch to next sheet (stops at last sheet)
• 0: Jump to first column in current row
• ^: Jump to first non-empty column in current row
• $: Jump to last column in current row
• gg: Jump to first row in current column
• G: Jump to last row in current column
• Ctrl+←: If current cell is empty, jump to the first non-empty cell to the left; if current cell is not empty, jump to the last non-empty cell to the left
• Ctrl+→: If current cell is empty, jump to the first non-empty cell to the right; if current cell is not empty, jump to the last non-empty cell to the right
• Ctrl+↑: If current cell is empty, jump to the first non-empty cell above; if current cell is not empty, jump to the last non-empty cell above
• Ctrl+↓: If current cell is empty, jump to the first non-empty cell below; if current cell is not empty, jump to the last non-empty cell below
• i: Edit current cell
• y: Copy current cell content
• d: Cut current cell content
• p: Paste clipboard content to current cell
• /: Start forward search
• ?: Start backward search
• n: Jump to next search result
• N: Jump to previous search result
• :: Enter command mode (for Vim-like commands)

Edit Mode

In edit mode:

• Enter: Confirm edit
• Esc: Cancel edit
• Formulas can be entered by starting with =

Search Mode

Enter search mode by pressing / (forward search) or ? (backward search):

• Type your search query
• Enter: Execute search and jump to the first match
• Esc: Cancel search
• n: Jump to next match (after search is executed)
• N: Jump to previous match (after search is executed)
• Search results are highlighted in yellow
• Search uses row-first, column-second order (searches through each row from left to right, then moves to the next row)

Command Mode

Enter command mode by pressing :. Available commands:

Column Width Commands

• :cw fit - Auto-adjust current column width to fit content
• :cw fit all - Auto-adjust all column widths to fit content
• :cw min - Minimize current column width (max 15 or content width)
• :cw min all - Minimize all column widths (max 15 or content width)
• :cw [number] - Set current column width to specified value

JSON Export Commands

• :ej [h|v] [rows] - Export current sheet data to JSON format

  • h|v - Header direction: h for horizontal (top rows), v for vertical (left columns)
  • rows - Number of header rows (for horizontal) or columns (for vertical)

• :eja [h|v] [rows] - Export all sheets to a single JSON file

  • Uses the same parameters as :ej
  • Creates a JSON object with sheet names as keys and sheet data as values

The output filename is automatically generated in one of these formats:

• For single sheet: original_filename_sheet_SheetName_YYYYMMDD_HHMMSS.json
• For all sheets: original_filename_all_sheets_YYYYMMDD_HHMMSS.json

Vim-like Commands

• :w - Save file without exiting

• :wq or :x - Save and exit

• :q - Quit (will warn if there are unsaved changes)

• :q! - Force quit without saving See File Saving Logic for details on how files are saved.

• :y - Copy current cell content

• :d - Cut current cell content

• :put or :pu - Paste clipboard content to current cell

• :[cell] - Jump to cell (e.g., :A1, :B10). Supports both uppercase and lowercase column letters (:a1 works the same as :A1)

Sheet Management Commands

• :sheet [name/number] - Switch to sheet by name or index (1-based)
• :delsheet - Delete the current sheet (prevents deleting the last sheet)

Row and Column Management Commands

• :dr - Delete the current row
• :dr [row] - Delete a specific row (e.g., :dr 5 deletes row 5)
• :dr [start] [end] - Delete a range of rows (e.g., :dr 5 10 deletes rows 5 through 10)
• :dc - Delete the current column
• :dc [col] - Delete a specific column (e.g., :dc A or :dc a or :dc 1 all delete column A)
• :dc [start] [end] - Delete a range of columns (e.g., :dc A C or :dc a c deletes columns A through C)

Other Commands

• :nohlsearch or :noh - Disable search highlighting
• :help - Show available commands

File Saving Logic

Excel-CLI uses a non-destructive approach to file saving:

• When you save a file (using :w, :wq, or :x), the application checks if any changes have been made.
• If no changes have been made, no new file is created, and a "No changes to save" message is displayed.
• If changes have been made, a new file is created with a timestamp in the filename, following the format original_filename_YYYYMMDD_HHMMSS.xlsx.
• The original file is never modified.

Technical Stack

• Written in Rust
• Uses ratatui library for terminal UI
• crossterm for terminal input handling
• calamine library for reading Excel files
• rust_xlsxwriter for writing Excel files
• serde_json for JSON serialization

License

MIT