Inspect a workbook

The inspection answers two questions about a workbook: what is in it, and what another operation would see in it. It reads the file and reports; it writes nothing, creates no output, and leaves the original untouched.

What it reports

• Worksheets, in workbook order, each with its visibility (visible, hidden, or very hidden), the size of its used range, and how many rows sit below its header row.
• The header row each worksheet would be read from. It comes from the same rule the consolidation and the workbook split apply, rather than from a second header detection written for the report, so the answer moves with the operations: the first row holding more than half as many values as the fullest of the rows below it, or at most one value fewer, with the rows above it skipped when a blank row sets them apart from the header or they are banners merged across columns. The rule is described under Choose a header row; --header-row names a row instead.
• Column headers from that row, blanks filled in and repeats made unique the way an operation would name them. A column that holds nothing in the header row or under it is a spacer and is left out, exactly as a consolidation leaves it out, so the column list can be shorter than the width of the used range reported beside it.
• Sample values: up to five distinct non-empty values per column, in the order the rows carry them. Values are reported as the workbook stores them, with nothing type-inferred, so the number 1 and the text 1 stay apart. The browser tool quotes text samples and leaves numbers and booleans bare, so you can see which of the two a cell holds.
• Excel Tables and named ranges the package declares, with the sheet and range each one covers.
• Warnings from the operation itself, naming what a later operation would stumble on: worksheets left out of the description, a worksheet with no header row to match columns by, or formulas Excel never calculated, which every operation reads as blank (counted in formulaCellsWithoutCachedValues).

When to use it

Reach for it before an operation rather than after a surprising result:

• A consolidation unioned more columns than you expected. The header preview shows which spellings the sources actually carry.
• A split reports no rows for a column you can see in Excel. The report says which header row each worksheet resolves to, and whether the data sits on a worksheet an operation would skip.
• You are about to name a worksheet, Excel Table, or named range in another command and want the spelling the workbook stores.

The online tool

The browser tool takes .xlsx and .xlsm workbooks, reads them in the page, and renders the report. There is no Run button and no download, because the inspection produces no file: choosing a workbook is the whole interaction.

The same report is embedded in the two operating pages that read a workbook before they write one, folded away under "Look inside this workbook" on the split page and "Look inside a workbook" on the consolidate page, which chooses among the workbooks you added. Nothing is inspected until you open the disclosure. The consolidate page's report follows that page's "Include hidden worksheets" choice, so it describes the worksheets that run would read; the split page's report always covers hidden worksheets, because the default split filters them too.

One interface default differs from the library's. The browser tool describes hidden and very hidden worksheets by default, since a page whose job is to say what is in a file would otherwise leave out the worksheets people most often go looking for. Every worksheet in the report carries its visibility, and the "Include hidden worksheets" checkbox turns the description back to what an operation that skips them would find.

From the command line

consultchimps sheets inspect clients.xlsx
consultchimps sheets inspect --sheet North --sheet South clients.xlsx

The command reads an .xlsx or .xlsm workbook and writes nothing: it prints the description as a report, then the plain-language explanation of the result and its warnings. --sheet names one worksheet and may be repeated, --header-row names the row the headers sit on, --hidden includes hidden worksheets, and --samples sets how many sample values each column reports, from 0 to 5. Placing the global --json before the command returns the description beside the operation result instead. The CLI reference documents them in full.

TypeScript API

import { describeWorkbook } from "@consultchimps/xlsx";

const { description, result } = await describeWorkbook("review-log.xlsx", {
  includeHiddenSheets: true,
});

for (const sheet of description.sheets) {
  console.log(`${sheet.name} (${sheet.visibility})`);
  console.log(`  header row: ${sheet.headerRow ?? "none found"}`);
  for (const column of sheet.columns) {
    console.log(`  ${column.header}: ${column.sampleValues.join(", ")}`);
  }
}

console.log(result.metrics.worksheets, result.warnings);

describeWorkbookBytes is the byte-level twin, and the one the browser tool runs. Both produce a structurally identical description for the same workbook. The libraries guide covers the options and the result shape in full, and what the Excel operations preserve records the inspection beside the operations that do write files.