📊 Excel Inspector

A powerful CLI tool to convert Excel files (.xlsx, .xlsm) to structured JSON - Built with AI workflows in mind

✨ Features

• 🚀 Fast: Convert Excel to JSON in seconds
• 🤖 AI-First: Perfect output format for LLM consumption
• 📊 Smart Analysis: Auto-detects column types and provides statistics
• 🎯 Flexible: Process entire workbooks or specific sheets
• 💻 CLI & Programmatic: Use as command or import as module
• 🔍 Preview Mode: Check structure without loading all data

📦 Installation

Global (recommended for CLI usage)

npm install -g excel-inspector-cli

Local (for use in projects)

npm install excel-inspector-cli

💡 New to Excel Inspector? Check out the Quick Start Guide for a 60-second tour!

🚀 Quick Start

Basic Usage

# Inspect entire workbook
excel-inspector myfile.xlsx

# Inspect specific sheet
excel-inspector myfile.xlsx --sheet "Sales Data"

# Preview structure only (no data)
excel-inspector myfile.xlsx --headers-only

# Limit rows (useful for large files)
excel-inspector myfile.xlsx --limit 100

Output

The tool outputs structured JSON to stdout:

{
  "metadata": {
    "filename": "myfile.xlsx",
    "sheets": ["Sheet1", "Sheet2"],
    "sheetCount": 2,
    "generatedAt": "2026-02-13T10:30:00.000Z"
  },
  "sheets": {
    "Sheet1": {
      "headers": ["Product", "Price", "Stock"],
      "rowCount": 150,
      "columnStats": {
        "Product": {
          "nonEmptyCount": 150,
          "types": ["string"],
          "sampleValues": ["Widget A", "Widget B", "Widget C"]
        },
        "Price": {
          "nonEmptyCount": 148,
          "types": ["number"],
          "sampleValues": [19.99, 29.99, 9.99]
        }
      },
      "data": [
        { "Product": "Widget A", "Price": 19.99, "Stock": 50 },
        { "Product": "Widget B", "Price": 29.99, "Stock": 30 }
      ]
    }
  }
}

📖 Usage Guide

Command Line Options

| Option | Description | Example | |--------|-------------|---------| | --sheet "Name" | Process only specific sheet | --sheet "Sales" | | --headers-only | Return structure only (no data) | --headers-only | | --limit N | Limit to N rows per sheet | --limit 50 | | --raw | Output JSON in single line | --raw | | --help | Show help | --help |

Common Use Cases

1. Quick Preview of Large Files

excel-inspector huge-file.xlsx --headers-only

Returns only sheet names and column headers, perfect for understanding structure without loading GBs of data.

2. Extract Single Sheet

excel-inspector report.xlsx --sheet "Q4 Summary" > q4-data.json

3. Sample Data for Testing

excel-inspector database.xlsx --limit 10 > sample.json

4. Pipe to jq for Filtering

excel-inspector data.xlsx | jq '.sheets.Sheet1.data[] | select(.Price > 20)'

5. Use in Scripts

#!/bin/bash
DATA=$(excel-inspector inventory.xlsx --sheet "Stock" --raw)
echo $DATA | jq '.sheets.Stock.rowCount'

💻 Programmatic Usage (Node.js)

const inspectExcel = require('excel-inspector-cli');

// Inspect file
const result = await inspectExcel('data.xlsx', {
  sheet: 'Sales',          // Optional: specific sheet
  headersOnly: false,      // Optional: structure only
  limit: 100               // Optional: row limit
});

console.log(result.sheets.Sales.data);

🤖 For AI/LLM Usage

This tool was specifically designed for AI workflows. See AI-USAGE.md for detailed instructions on how AIs should use this tool when users request Excel analysis.

Quick Protocol for AIs:

1. Run inspector with --headers-only first
2. Present structured summary to user
3. Offer options: view data, analyze structure, export, etc.
4. Load full data only if needed

🛠️ Development

# Clone repository
git clone https://github.com/FrancoJacquet/excel-inspector.git
cd excel-inspector

# Install dependencies
npm install

# Run locally
node index.js test-file.xlsx

# Run tests (if available)
npm test

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Ideas for contributions:

• Add CSV export option
• Support for older Excel formats (.xls)
• Add TypeScript definitions
• Performance optimizations for huge files
• More column statistics (min/max/avg for numbers)

📝 Changelog

See CHANGELOG.md for version history.

📄 License

MIT © Excel Inspector Contributors

🙏 Acknowledgments

Built with:

• SheetJS - Excel parsing engine
• Designed for seamless integration with AI assistants (Claude, ChatGPT, etc.)

💡 Why Excel Inspector?

Most Excel parsing tools either:

• Return data in formats difficult for AIs to consume
• Lack contextual metadata (column types, row counts, etc.)
• Don't handle large files efficiently
• Require complex APIs

Excel Inspector solves this by providing a simple CLI with rich, structured JSON output that both humans and AIs can easily understand and process.

🔗 Links

• NPM Package
• GitHub Repository
• Report Issues
• Quick Start Guide - Get started in 60 seconds!
• AI Usage Guide - For AI assistants
• Contributing Guide - How to contribute
• Changelog - Version history
• Examples - Sample scripts and usage

Made with ❤️ for developers and AI assistants