Excel-CLI

An Excel CLI for AI, scripting, and terminal users. Inspect and read headlessly via a stable JSON API, or browse and edit interactively with a Vim-like TUI.

Features

• Browse and navigate Excel worksheets with Vim-like hotkeys
• Create, switch, and delete sheets in multi-sheet workbooks
• Edit cell contents directly in the terminal
• Export data to JSON format
• Select, filter, paginate, and stream read results for automation
• Run workbook and sheet quality checks with stable JSON findings
• Delete rows and columns
• 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 --locked

Option 2: Download from GitHub Release

1. Visit the GitHub Releases
2. Download the pre-compiled binary for your operating system
3. 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 . --locked

Uninstallation

cargo uninstall excel-cli

Usage

# Inspect workbook metadata
excel-cli inspect workbook path/to/your/file.xlsx

# Inspect a single sheet
excel-cli inspect sheet path/to/your/file.xlsx --sheet Orders
excel-cli inspect sheet path/to/your/file.xlsx --sheet-index 0

# Sample data from a sheet
excel-cli inspect sample path/to/your/file.xlsx --sheet Orders --rows 10

# Inspect columns with auto-detected headers
excel-cli inspect columns path/to/your/file.xlsx --sheet Orders --header-row auto

# Inspect table-like regions in a sheet
excel-cli inspect tables path/to/your/file.xlsx --sheet Orders

# Read a single cell
excel-cli read cell path/to/your/file.xlsx --sheet Orders --cell B2

# Read a range
excel-cli read range path/to/your/file.xlsx --sheet Orders --range A1:F20

# Read rows (with auto-detected header)
excel-cli read rows path/to/your/file.xlsx --sheet Orders

# Read rows with explicit header row (1-based)
excel-cli read rows path/to/your/file.xlsx --sheet Orders --header-row 1

# Read selected columns as records
excel-cli read records path/to/your/file.xlsx --sheet Orders --select order_id,total,status

# Filter, paginate, and stream records as JSON Lines
excel-cli read records path/to/your/file.xlsx --sheet Orders \
  --filter status:eq:open \
  --filter total:gte:100 \
  --limit 50 \
  --output-shape jsonl

# Check workbook data quality with the full rule set
excel-cli check path/to/your/file.xlsx

# Check one sheet with selected rules
excel-cli check path/to/your/file.xlsx --sheet Orders --rules duplicate_values,type_drift

# Return only warning and error findings
excel-cli check path/to/your/file.xlsx --severity-threshold warning

# Open interactive TUI browser
excel-cli ui path/to/your/file.xlsx

Command-line Options

All headless commands (inspect, read, check) default to JSON output. Use --format text for human-readable output.

Global output rules:

• stdout only contains results
• stderr only contains errors
• Success returns exit code 0
• Failure returns a non-zero exit code (see Exit Codes below)
• Empty cells output null in JSON mode and empty string in text mode

Reading Rows and Records

read rows returns positional arrays by default. Use --output-shape records to return objects keyed by the resolved header row, or use read records when record-shaped output is the default.

excel-cli read rows report.xlsx --sheet Orders --output-shape rows
excel-cli read rows report.xlsx --sheet Orders --output-shape records
excel-cli read records report.xlsx --sheet Orders

--select keeps only named columns. Names come from the resolved header row, with duplicate or blank headers made stable in the same way as inspect columns.

excel-cli read records report.xlsx --sheet Orders --select order_id,customer,total

--filter field:op:value filters rows by column name. Repeat --filter to combine conditions with AND semantics. Supported operators are eq, ne, gt, gte, lt, lte, contains, regex, isnull, and notnull.

excel-cli read records report.xlsx --sheet Orders --filter status:eq:open
excel-cli read records report.xlsx --sheet Orders --filter total:gte:100
excel-cli read records report.xlsx --sheet Orders --filter customer:contains:Inc
excel-cli read records report.xlsx --sheet Orders --filter order_id:regex:^INV-[0-9]+$
excel-cli read records report.xlsx --sheet Orders --filter optional_note:isnull:

--limit and --offset apply after filtering. --non-empty removes rows where every cell is empty. No-match filters are successful queries: they return an empty rows or records array with exit code 0.

excel-cli read records report.xlsx --sheet Orders \
  --filter status:eq:open \
  --offset 25 \
  --limit 25 \
  --non-empty

--output-shape jsonl writes newline-delimited JSON records directly to stdout instead of the standard envelope. It uses the same selection, filtering, pagination, and header resolution rules as record output.

excel-cli read records report.xlsx --sheet Orders --output-shape jsonl

Invalid selected columns, unknown filter columns, unsupported operators, malformed filters, invalid numeric comparisons, and invalid regular expressions return structured invalid_query errors with exit code 6.

Quality Checks

check runs the fixed quality-rule registry against a whole workbook or a single sheet and emits the same stable JSON envelope as the other headless commands. By default it scans every sheet, returns info, warning, and error findings, exits 1 when the filtered result set is non-empty, and exits 0 when no findings remain after filtering.

Supported rules:

• blank_headers: flag blank header cells inside the detected header row
• duplicate_headers: flag duplicate normalized header names
• blank_rows: flag fully blank rows inside the used range
• blank_columns: flag fully blank columns inside the used range
• null_ratio: flag columns with blank-value ratios above the built-in thresholds
• duplicate_values: flag repeated values in the candidate identifier column
• type_drift: flag mixed dominant and drift data types in a column
• formula_presence: report sheets that still contain formulas in the checked data region

Use --sheet <name> to limit the scan to one sheet, --rules <comma,separated,ids> to run a subset in registry order, and --severity-threshold <info|warning|error> to filter returned findings. data.summary counts only the returned findings, while data.stats.finding_count_before_threshold preserves the total before threshold filtering and data.stats.rules_run records the normalized rule order.

excel-cli check report.xlsx
excel-cli check report.xlsx --sheet 客户 --rules blank_headers,duplicate_headers
excel-cli check report.xlsx --rules null_ratio,duplicate_values,type_drift --severity-threshold warning

Exit Codes

Code	Meaning
0	Success
1	Check completed with findings
2	Invalid command or arguments
3	File cannot be opened or read
4	Workbook parse failure or unsupported format
5	Sheet, cell, range, or target not found
6	Invalid query or check rule
7	Internal error

Output Format

Headless success responses follow a stable envelope:

{
  "schema_version": "1.0",
  "command": "inspect.sheet",
  "file": { "path": "report.xlsx", "format": "xlsx" },
  "target": { "sheet": "Orders", "sheet_index": 1 },
  "meta": {},
  "data": { ... },
  "warnings": []
}

Structure Inspection

inspect columns profiles each column in a sheet so you can choose stable field names for later commands. The response data includes columns, where each column has index, original name, generated safe_name, is_duplicate, best-effort inferred_type, non_null_ratio, formula_ratio, and sample_values. The response metadata includes header_row_mode, resolved_header_row, column_count, and data_row_count.

excel-cli inspect columns path/to/your/file.xlsx --sheet Orders --header-row auto
excel-cli inspect columns path/to/your/file.xlsx --sheet Orders --header-row 2 --format text

inspect tables detects contiguous table-like regions in a sheet. The response data includes data.candidates; each candidate includes range, header_row, column_count, row_count, and confidence. The response metadata includes candidate_count.

excel-cli inspect tables path/to/your/file.xlsx --sheet Orders
excel-cli inspect tables path/to/your/file.xlsx --sheet Orders --format text

Headless error responses follow a stable envelope:

{
  "schema_version": "1.0",
  "command": "read.rows",
  "file": { "path": "report.xlsx", "format": "xlsx" },
  "error": {
    "code": "target_not_found",
    "message": "Sheet 'Orders' not found",
    "details": {}
  }
}

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 changes, sheet creation/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

• :addsheet [name] - Add a new sheet after the current sheet
• :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 all keyboard-shortcut reference

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 lazy loading is enabled, all unloaded sheets are loaded before saving so the workbook content is preserved
• 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

Contributing

Please see CONTRIBUTING.md for branch naming, commit message, and Pull Request conventions.

License

MIT