XL CLI - Excel Operations

Installation

Check if installed: which xl || echo "not installed"

If not installed, download native binary (no JDK required):

macOS/Linux:

# Detect platform and install __XL_VERSION__
PLATFORM="$(uname -s)-$(uname -m)"
case "$PLATFORM" in
  Linux-x86_64)  BINARY="xl-__XL_VERSION__-linux-amd64" ;;
  Darwin-x86_64) BINARY="xl-__XL_VERSION__-darwin-amd64" ;;
  Darwin-arm64)  BINARY="xl-__XL_VERSION__-darwin-arm64" ;;
  *) echo "Unsupported platform: $PLATFORM" && exit 1 ;;
esac
mkdir -p ~/.local/bin
curl -sL "https://github.com/TJC-LP/xl/releases/download/v__XL_VERSION__/$BINARY" -o ~/.local/bin/xl
chmod +x ~/.local/bin/xl

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/TJC-LP/xl/releases/download/v__XL_VERSION__/xl-__XL_VERSION__-windows-amd64.exe" -OutFile "$env:LOCALAPPDATA\xl.exe"
# Add to PATH or move to a directory in PATH

Alternative (requires JDK 17+):

curl -sL "https://github.com/TJC-LP/xl/releases/download/v__XL_VERSION__/xl-cli-__XL_VERSION__.tar.gz" | tar xz -C /tmp
cd /tmp && ./install.sh

Contents

• Quick Reference
• Sheet Handling
• Sheet Management
• Cell Operations
• Batch Operations
• Styling
• Row/Column Operations
• Output Formats
• Workflows
• Command Reference

Quick Reference

# Read operations
xl -f <file> sheets                    # List sheets with stats
xl -f <file> names                     # List defined names (named ranges)
xl -f <file> -s <sheet> bounds         # Used range
xl -f <file> -s <sheet> view <range>   # View as table
xl -f <file> -s <sheet> cell <ref>     # Cell details + dependencies
xl -f <file> -s <sheet> search <pattern>  # Find cells
xl -f <file> -s <sheet> stats <range>  # Calculate statistics (count, sum, min, max, mean)
xl -f <file> -s <sheet> eval <formula> # Evaluate formula

# Output formats
xl -f <file> -s <sheet> view <range> --format json
xl -f <file> -s <sheet> view <range> --format csv --show-labels
xl -f <file> -s <sheet> view <range> --format png --raster-output out.png

# Write operations (require -o)
xl -f <file> -s <sheet> -o <out> put <ref> <value>
xl -f <file> -s <sheet> -o <out> putf <ref> <formula>

# Style operations (require -o)
xl -f <file> -s <sheet> -o <out> style <range> --bold --bg yellow
xl -f <file> -s <sheet> -o <out> style <range> --bg "#FF6600" --fg white

# Row/Column operations (require -o)
xl -f <file> -s <sheet> -o <out> row <n> --height 30
xl -f <file> -s <sheet> -o <out> col <letter> --width 20 --hide

# Sheet management (require -o)
xl -f <file> -o <out> add-sheet "NewSheet"
xl -f <file> -o <out> remove-sheet "OldSheet"
xl -f <file> -o <out> rename-sheet "Old" "New"
xl -f <file> -o <out> move-sheet "Sheet1" --to 0
xl -f <file> -o <out> copy-sheet "Template" "Copy"

# Cell operations (require -o and -s)
xl -f <file> -s <sheet> -o <out> merge A1:C1
xl -f <file> -s <sheet> -o <out> unmerge A1:C1

# Batch operations (require -o)
xl -f <file> -s <sheet> -o <out> batch <json-file>
xl -f <file> -s <sheet> -o <out> batch -              # Read from stdin

# Formula dragging (putf with range)
xl -f <file> -s <sheet> -o <out> putf <range> <formula>  # Drags formula over range

# Create new workbook
xl new <output>                                          # Default Sheet1
xl new <output> --sheet Data --sheet Summary             # Multiple sheets

Sheet Handling

Commands default to first sheet. For multi-sheet files, always specify explicitly:

# Method 1: --sheet flag
xl -f data.xlsx --sheet "P&L" view A1:D10

# Method 2: Qualified A1 syntax
xl -f data.xlsx view "P&L!A1:D10"
xl -f data.xlsx eval "=SUM(Revenue!A1:A10)"

Workflow: Always start with xl -f file.xlsx sheets to discover sheet names.

Sheet Management

Modify workbook structure with these commands (all require -o for output):

Add / Remove Sheets

# Add new empty sheet (appends to end)
xl -f data.xlsx -o out.xlsx add-sheet "NewSheet"

# Add sheet at specific position
xl -f data.xlsx -o out.xlsx add-sheet "Summary" --before "Sheet1"
xl -f data.xlsx -o out.xlsx add-sheet "Notes" --after "Data"

# Remove sheet
xl -f data.xlsx -o out.xlsx remove-sheet "Scratch"

Rename / Move / Copy Sheets

# Rename
xl -f data.xlsx -o out.xlsx rename-sheet "Sheet1" "Summary"

# Move to position (0-based index)
xl -f data.xlsx -o out.xlsx move-sheet "Notes" --to 0

# Move relative to another sheet
xl -f data.xlsx -o out.xlsx move-sheet "Notes" --after "Summary"
xl -f data.xlsx -o out.xlsx move-sheet "Notes" --before "Data"

# Copy (duplicate with new name)
xl -f data.xlsx -o out.xlsx copy-sheet "Template" "Q1 Report"

Cell Operations

Merge / Unmerge Cells

Merge combines cells into one; unmerge separates them.

# Merge header row
xl -f data.xlsx -s Sheet1 -o out.xlsx merge A1:D1

# Unmerge
xl -f data.xlsx -s Sheet1 -o out.xlsx unmerge A1:D1

Note: HTML output shows merged cells with colspan/rowspan. Markdown tables cannot represent merges.

Statistics

Calculate statistics for numeric values in a range:

xl -f data.xlsx -s Sheet1 stats B2:B100
# Output: count: 99, sum: 12345.00, min: 10.00, max: 500.00, mean: 124.70

Formula Dragging

When putf receives a range, it drags the formula Excel-style:

# Fill B2:B10 with formulas, shifting references
xl -f data.xlsx -s Sheet1 -o out.xlsx putf B2:B10 "=A2*1.1"

# Result:
# B2: =A2*1.1
# B3: =A3*1.1
# ...

# Use $ to anchor references
xl -f data.xlsx -s Sheet1 -o out.xlsx putf B2:B10 "=SUM(\$A\$1:A2)"

# Result:
# B2: =SUM($A$1:A2)
# B3: =SUM($A$1:A3)
# ...

Anchor modes:

Batch Operations

Apply multiple cell operations atomically from JSON input:

# From file
xl -f data.xlsx -s Sheet1 -o out.xlsx batch operations.json

# From stdin
echo '[{"op":"put","ref":"A1","value":"Hello"},{"op":"putf","ref":"B1","value":"=A1&\" World\""}]' \
  | xl -f data.xlsx -s Sheet1 -o out.xlsx batch -

JSON Format:

[
  {"op": "put", "ref": "A1", "value": "Hello"},
  {"op": "put", "ref": "A2", "value": "123"},
  {"op": "putf", "ref": "B1", "value": "=A1*2"},
  {"op": "put", "ref": "Sheet2!C1", "value": "Cross-sheet"}
]

Styling

Apply formatting with style <range> command.

Style Behavior: Styles are merged by default (new properties combine with existing). Use --replace to replace the entire style instead.

Colors: Named (red, navy), hex (#FF6600), or RGB (rgb(100,150,200)). See reference/COLORS.md for full color list.

# Header styling
xl -f data.xlsx -o out.xlsx style A1:E1 --bold --bg navy --fg white --align center

# Currency column
xl -f data.xlsx -o out.xlsx style B2:B100 --format currency

Row/Column Operations

# Row height and visibility
xl -f data.xlsx -o out.xlsx row 5 --height 30
xl -f data.xlsx -o out.xlsx row 10 --hide
xl -f data.xlsx -o out.xlsx row 10 --show

# Column width and visibility
xl -f data.xlsx -o out.xlsx col B --width 20
xl -f data.xlsx -o out.xlsx col C --hide

Output Formats

See reference/OUTPUT-FORMATS.md for detailed specs.

Raster options: --dpi <n>, --quality <n>, --show-labels, --rasterizer <name>

# Visual analysis (Claude vision)
xl -f data.xlsx view A1:F20 --format png --raster-output /tmp/sheet.png --show-labels

Workflows

Explore Unknown Spreadsheet

xl -f data.xlsx sheets                     # List sheets with cell counts
xl -f data.xlsx names                      # List defined names (named ranges)
xl -f data.xlsx -s "Sheet1" bounds         # Get used range
xl -f data.xlsx -s "Sheet1" view A1:E20    # View data
xl -f data.xlsx -s "Sheet1" stats B2:B100  # Quick statistics

Formula Analysis

xl -f data.xlsx -s Sheet1 view --formulas A1:D10     # Show formulas
xl -f data.xlsx -s Sheet1 cell C5                    # Dependencies
xl -f data.xlsx -s Sheet1 eval "=SUM(A1:A10)" --with "A1=500"  # What-if

See reference/FORMULAS.md for supported functions.

Create Formatted Report

xl -f template.xlsx -s Sheet1 -o report.xlsx put A1 "Sales Report"
xl -f report.xlsx -s Sheet1 -o report.xlsx style A1:E1 --bold --bg navy --fg white
xl -f report.xlsx -s Sheet1 -o report.xlsx style B2:B100 --format currency
xl -f report.xlsx -s Sheet1 -o report.xlsx col A --width 25

Multi-Sheet Workbook Setup

# Create workbook (default sheet: Sheet1)
xl new output.xlsx

# Create with custom sheet name
xl new output.xlsx --sheet-name "Data"

# Create with multiple sheets in one command
xl new output.xlsx --sheet Data --sheet Summary --sheet Notes

# Add more sheets to existing workbook
xl -f output.xlsx -o output.xlsx add-sheet "Archive" --after "Notes"
xl -f output.xlsx -o output.xlsx copy-sheet "Summary" "Q1 Summary"

Command Reference

Global Options

View Options

Search Options

Eval Options

Cell Options

Sheet Management Commands

Cell Operation Commands