Excel-CLI is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install excel-cli

It will make the excel-cli command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall excel-cli uninstalls.

Adding `excel_cli` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add excel-cli

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

excel-cli = "0.3.0"

The excel_cli library will be automatically available globally. Read the excel_cli library documentation.

Back to the crate overview.

Readme

Excel-CLI

A lightweight terminal-based Excel viewer with Vim-like navigation for viewing, editing, and exporting Excel data to JSON format.

English | 中文

Features

Browse and navigate Excel worksheets with Vim-like hotkeys
Switch between sheets in multi-sheet workbooks
Edit cell contents directly in the terminal
Export data to JSON format
Delete rows, columns, and sheets
Search functionality with highlighting
Command mode for advanced operations

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: Download from GitHub Release

Visit the GitHub Releases
Download the pre-compiled binary for your operating system
Place the executable in your system path, or run it directly from the download location

Linux and macOS users may need to add execute permissions first

Option 3: 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 in Excel: '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 Excel. Default: 1
--lazy-loading, -l: Enable lazy loading for large Excel files (only loads data when needed)

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
Content Panel: Displays the full content of the currently selected cell
Notification Panel: Displays operation feedback and system notifications
Status Bar: Displays operation hints and current input commands

Keyboard Shortcuts

h, j, k, l or arrow keys: Move between cells (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+← (or Command+← on Mac): 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+→ (or Command+→ on Mac): 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+↑ (or Command+↑ on Mac): 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+↓ (or Command+↓ on Mac): 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
Enter: Edit current cell
y: Copy current cell content
d: Cut current cell content
p: Paste clipboard content to current cell
u: Undo the last operation (edit, row/column/sheet deletion)
Ctrl+r: Redo the last undone operation
/: 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)

Vim Edit Mode

When editing cell content (press Enter to enter edit mode):

Mode Switching:
- Esc: Exit Vim mode and save changes
- i: Enter Insert mode
- v: Enter Visual mode
Navigation (in Normal mode):
- h, j, k, l: Move cursor left, down, up, right
- w: Move to next word
- b: Move to beginning of word
- e: Move to end of word
- $: Move to end of line
- ^: Move to first non-blank character of line
- gg: Move to first line
- G: Move to last line
Editing Operations:
- x: Delete character under cursor
- D: Delete to end of line
- C: Change to end of line
- o: Open new line below and enter Insert mode
- O: Open new line above and enter Insert mode
- A: Append at end of line
- I: Insert at beginning of line
Visual Mode Operations:
- y: Yank (copy) selected text
- d: Delete selected text
- c: Change selected text (delete and enter Insert mode)
Operator Commands:
- y{motion}: Yank text specified by motion
- d{motion}: Delete text specified by motion
- c{motion}: Change text specified by motion
Clipboard Operations:
- p: Paste yanked or deleted text
- u: Undo last change
- Ctrl+r: Redo last undone change

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

The JSON files are saved in the same directory as the original Excel file.

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 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

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 new file is created without any styling
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

Installing the command-line executable

Adding excel_cli library as a dependency

Adding `excel_cli` library as a dependency