Analyze Any Spreadsheet from Your Terminal — No Excel Required

The Inherited Spreadsheet

Someone left. They left behind a spreadsheet. It has 14 tabs, nested VLOOKUP formulas three levels deep, and a pivot table that references a named range nobody can find. Your job is to update the Q2 numbers by Friday.

You open it in Excel. The cells are color-coded, but there is no legend. Column G is labeled "Adj. Rev. (excl.)" and column H is "Adj. Rev. (incl.)" — excluding and including what, exactly? A formula in row 47 references a cell in a hidden sheet. Another formula uses INDIRECT to build a cell reference from a string, which means the dependency arrows in Excel's formula auditing tool show nothing useful.

This is not a data problem. This is a comprehension problem. The spreadsheet works — probably. The numbers come out, and last quarter nobody complained. But you do not understand what it does, and changing something you do not understand is how you break a reporting pipeline the week before board review.

An inherited spreadsheet is an archaeological dig. Each layer was added by a different person, with different assumptions, and none of them left a map. Opening it in Excel gives you the artifact. What you need is a translator who speaks every version of Excel.

The Upgrade: AI Agent as Spreadsheet Translator

The standard approach to understanding a mystery spreadsheet is to click on individual cells, trace formula precedents one at a time, and build a mental model of the data flow. This works for a 20-row sheet. It does not work for a 14-tab workbook with 200 formulas.

Claude's documentation describes two relevant use cases: "Understand and extend an inherited spreadsheet" and "Organize your business finances." Both assume you upload the file to a chat interface, wait for a response, and iterate in a browser window.

The terminal approach is faster and more powerful. Instead of uploading to a GUI, you pipe the spreadsheet directly into an AI CLI agent. The agent reads the entire structure — every sheet, every formula, every named range — and produces a complete map of the workbook in one pass. No clicking. No tab-switching. No "can you also check sheet 3?"

The workflow:

1. Convert the spreadsheet to a readable format (if needed)
2. Pipe it into the AI agent with a structural analysis prompt
3. Get back a complete map: sheets, columns, formulas explained in plain language, dependencies between sheets, and flagged errors
4. Ask follow-up questions in the same session
5. Have the agent generate a corrected or updated version

Step 1: Get the Spreadsheet into Your Terminal

AI CLI agents read text. A .csv file is already text — pipe it directly. An .xlsx file needs conversion first.

For CSV files — no conversion needed:

cat quarterly_report.csv | claude -p "Map the structure of this spreadsheet. Explain every column, identify formulas or derived values, flag anything that looks like an error."

For XLSX files — convert to CSV with a one-liner using Python's built-in openpyxl or the lighter xlsx2csv:

pip install xlsx2csv

xlsx2csv -a quarterly_report.xlsx /tmp/sheets/

The -a flag exports all sheets as separate CSV files into the target directory. Now you have one CSV per tab:

/tmp/sheets/
  Revenue.csv
  Expenses.csv
  Headcount.csv
  Pivot_Summary.csv
  ...

Feed them all to the agent:

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  cat "$f"
done | claude -p "This is a multi-sheet spreadsheet exported as CSV. Map the complete structure: what each sheet does, how they relate to each other, what formulas or derived columns exist, and flag any errors or inconsistencies."

For Google Sheets — export as XLSX from the File menu, then use the same xlsx2csv conversion. Or export individual sheets as CSV directly.

Step 2: Structural Analysis — The Complete Map

The first pass should produce a structural map of the entire workbook. Here is a prompt that reliably produces useful output:

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  cat "$f"
done | claude -p "You are a spreadsheet auditor. Analyze this multi-sheet workbook and produce a structural report with these sections:

1. SHEET OVERVIEW — For each sheet: purpose, row count, column count, key columns
2. DATA FLOW — How sheets reference each other. Which sheet is the source of truth, which are derived
3. FORMULA AUDIT — Every formula or derived column, explained in plain English. Flag circular references, volatile functions (INDIRECT, OFFSET), and broken references
4. NAMED RANGES — Any named ranges or implicit ones (columns used as lookup keys)
5. ERROR FLAGS — Data type mismatches, hardcoded values that should be formulas, inconsistent formatting, missing data
6. DEPENDENCY GRAPH — A text-based diagram showing which sheets feed into which

Be specific. Cite cell references and exact values when flagging issues."

Typical output for a real-world financial workbook:

## SHEET OVERVIEW

### Revenue (Sheet 1)
- Purpose: Monthly revenue by product line
- Rows: 48 (12 months x 4 product lines)
- Key columns: Month, Product, Units, Unit_Price, Revenue
- Revenue column is derived: Units * Unit_Price

### Expenses (Sheet 2)
- Purpose: Monthly operating expenses by category
- Rows: 156 (12 months x 13 expense categories)
- Key columns: Month, Category, Budget, Actual, Variance
- Variance is derived: Budget - Actual
- WARNING: Rows 34-36 have hardcoded Variance values (42000, -15000, 8700)
  instead of formulas. These will not update if Budget or Actual changes.

### Pivot_Summary (Sheet 4)
- Purpose: Executive summary aggregating Revenue and Expenses
- WARNING: References a column "Adj_Revenue" that does not appear in any
  source sheet. The values appear to be manually entered.

That last warning — "Adj_Revenue does not appear in any source sheet" — is the kind of finding that would take you 20 minutes to discover manually. The agent catches it in seconds because it reads every sheet in one pass and cross-references all column names.

Step 3: Formula Explanation in Plain Language

Once you have the structural map, drill into specific formulas. This is where the agent earns its keep.

cat /tmp/sheets/Revenue.csv | claude -p "This is the Revenue sheet of a financial workbook. For every column that contains derived or calculated values:
1. Explain what the formula does in plain English
2. Identify the inputs (which cells or columns it depends on)
3. Rate the formula: SOLID (correct and robust), FRAGILE (works but breaks easily), or BROKEN (produces wrong results)
4. For FRAGILE or BROKEN formulas, explain why and suggest a fix"

Example output:

## Column E: Revenue
- Formula: Units (C) * Unit_Price (D)
- Plain English: Multiplies units sold by price per unit to get total revenue
- Rating: SOLID — straightforward multiplication, no edge cases

## Column F: Growth_Pct
- Formula: (Current_Revenue - Previous_Revenue) / Previous_Revenue * 100
- Plain English: Percentage change in revenue from the previous month
- Rating: FRAGILE — Row 2 (January) has no previous month, so the formula
  produces a division-by-zero error. Currently masked by an IFERROR wrapper
  that returns 0, which is misleading (0% growth is different from "no data").
- Fix: Use IFERROR to return "N/A" or leave the cell blank for the first month.

## Column G: Adj_Revenue
- Formula: None detected — all values appear to be hardcoded
- Plain English: Unknown. Column header suggests "adjusted revenue" but there
  is no formula showing what adjustment was applied.
- Rating: BROKEN — These values cannot be recalculated. If the source data
  changes, this column will be stale. Likely a manual override from a previous
  quarter that was never converted back to a formula.
- Fix: Determine the adjustment logic (tax? discount? FX conversion?) and
  replace hardcoded values with a formula.

This is the value. Not "here are your numbers" — but "here is what each number means, why it might be wrong, and how to fix it."

Step 4: Error Detection and Data Quality Checks

Beyond formula auditing, the agent catches structural problems that Excel silently ignores:

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  cat "$f"
done | claude -p "Audit this workbook for data quality issues. Check for:
1. Type mismatches — numbers stored as text, dates in inconsistent formats
2. Orphaned references — columns or sheets referenced nowhere
3. Duplicate rows or near-duplicates
4. Hardcoded values in cells that should contain formulas
5. Inconsistent naming — same entity spelled differently across sheets
6. Missing data — gaps in time series, incomplete rows
Output as a prioritized list: CRITICAL (will cause wrong results), WARNING (may cause confusion), INFO (cosmetic)."

The agent typically finds 5-15 issues in a workbook that has been in production for more than two quarters. The most common:

• Hardcoded overrides that were meant to be temporary but became permanent
• Date format inconsistencies — "March 2026" in one sheet, "2026-03" in another, "3/1/26" in a third
• Phantom columns — columns with headers but no data, or data but no headers
• Copy-paste artifacts — a row that was duplicated, edited, but the original was never removed

Step 5: Generate an Updated Version

Understanding the spreadsheet is step one. The actual task is usually "update the Q2 numbers." The agent can do this too.

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  cat "$f"
done | claude -p "This workbook contains Q1 actuals. I need to update it for Q2. Here are the Q2 numbers:

Product A: 1,240 units at \$102/unit
Product B: 890 units at \$205/unit
Product C: 445 units at \$89/unit
Product D: 2,100 units at \$47/unit

Update the Revenue sheet with these Q2 actuals. Recalculate all derived columns (Revenue, Growth_Pct). Fix the Adj_Revenue column by applying the same adjustment pattern visible in Q1 (if determinable) or flag it for manual input. Output the updated CSV."

The agent reads the existing structure, understands how formulas work, inserts the new data, recalculates derived values, and outputs a clean CSV. If something cannot be determined — like the mystery Adj_Revenue adjustment — it says so explicitly instead of guessing.

Save the output:

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  cat "$f"
done | claude -p "Update Revenue sheet with Q2 actuals: [numbers]. Output updated CSV only, no explanation." > /tmp/sheets/Revenue_Q2_updated.csv

CLAUDE.md for Recurring Spreadsheet Work

If you audit spreadsheets regularly — monthly financial close, quarterly board reports, weekly sales reconciliation — encode the rules in a CLAUDE.md file so every session starts with context:

# Spreadsheet Analysis Project

## Context
This directory contains quarterly financial workbooks exported from Google Sheets.
File naming: Q{quarter}_{year}_financial.xlsx (e.g., Q2_2026_financial.xlsx)

## Workbook Structure
- Revenue sheet: source of truth for sales data. Columns A-G.
- Expenses sheet: source of truth for opex. Columns A-F.
- Headcount sheet: FTE count by department. Updates quarterly.
- Pivot_Summary: executive summary — all values must be derived, never hardcoded.

## Known Issues
- Adj_Revenue in Revenue sheet is always hardcoded. Flag but do not attempt to fix.
- Expenses sheet uses "Marketing" and "Mktg" interchangeably — treat as same category.
- Growth_Pct formula in row 2 always shows 0% — this is the IFERROR fallback, not real data.

## Output Standards
- All monetary values in USD, no cents (round to nearest dollar)
- Dates as YYYY-MM format
- When generating updated CSVs, preserve the original column order exactly
- Flag any value that changed by more than 50% quarter-over-quarter

With this file in place, claude sessions automatically load these rules. You stop repeating "remember that Adj_Revenue is hardcoded" every time.

The Split-Terminal Workflow

Spreadsheet analysis benefits from seeing the data and the analysis side by side. The most effective setup:

Left pane: The agent session. You pipe in the spreadsheet, ask questions, request updates. The agent streams its structural analysis, formula explanations, and error reports.

Right pane: The original spreadsheet data, or the CSV files opened in a viewer. As the agent references specific cells, columns, or sheets, you can verify immediately without switching windows.

For the update workflow, the split is even more useful:

1. Left pane: agent generates updated CSV
2. Right pane: diff between original and updated files shows exactly what changed

diff /tmp/sheets/Revenue.csv /tmp/sheets/Revenue_Q2_updated.csv

You see every change the agent made. No hidden modifications. No "trust me, I updated it." Every delta is visible.

Handling Large or Complex Workbooks

For workbooks that exceed the context window — hundreds of thousands of rows, dozens of sheets — use a staged approach:

Stage 1: Headers only. Extract just the column headers from each sheet to get a structural overview without consuming tokens on data:

for f in /tmp/sheets/*.csv; do
  echo "=== Sheet: $(basename "$f" .csv) ==="
  head -1 "$f"
done | claude -p "These are the column headers from each sheet of a workbook. Map the structure: what each sheet likely does, how they probably relate, which columns are likely derived. Identify which sheets I should analyze in detail first."

Stage 2: Priority sheets. Based on the agent's recommendations, analyze the most important sheets in full:

cat /tmp/sheets/Revenue.csv | claude -p "Full analysis of this Revenue sheet. Map every column, explain derived values, flag errors."

Stage 3: Cross-sheet validation. Once individual sheets are understood, validate the connections:

cat /tmp/sheets/Revenue.csv /tmp/sheets/Pivot_Summary.csv | claude -p "These two sheets should be linked: Pivot_Summary should aggregate Revenue. Verify: are the summary values consistent with the detail? Flag any discrepancy."

This staged approach keeps each prompt focused and within token limits, while still producing a complete workbook analysis.

When This Works Best (and When It Does Not)

Use AI CLI spreadsheet analysis for:

• Inherited workbooks where you need to understand the structure before changing anything
• Formula auditing — catching broken references, hardcoded overrides, circular dependencies
• Data quality checks before a monthly or quarterly close
• Converting a "magic spreadsheet" into documented, maintainable logic
• Quick updates when you understand the structure but want the agent to handle the mechanical work

Stick with Excel or Google Sheets when:

• You need interactive pivot tables or charts that update with slicers
• The workbook uses VBA macros (the agent can read them but cannot execute them)
• You need real-time collaboration with non-technical stakeholders
• The task is purely visual — conditional formatting, layout adjustments

The sweet spot is comprehension. When the problem is "I do not understand what this spreadsheet does," an AI agent reading the entire structure at once is faster than any amount of cell-clicking. When the problem is "I need to build a chart for the board deck," use the GUI.

Key Takeaways

An inherited spreadsheet is not a data problem — it is a comprehension problem. AI CLI agents solve it by reading the entire structure and translating it into language you can act on.

The core workflow:

1. Convert — xlsx2csv -a exports all sheets to CSV
2. Map — pipe into the agent for a complete structural analysis
3. Explain — drill into specific formulas for plain-language explanations
4. Audit — flag errors, hardcoded values, broken references
5. Update — generate corrected CSVs with new data
6. Diff — verify every change with diff before replacing the original

No Excel required. No GUI required. The spreadsheet comes to your terminal, and the agent translates it.