bim-excel

Read and write Excel files from the command line. The connective layer between Revit schedules, site data outputs, and any spreadsheet-based workflow — no Excel open, no copy-paste, no formula errors. Accepts piped input from any other bim driver; output can be piped forward.

Read and write Excel files from the command line. No Excel required to run it.

Verbs

Verb	What it does
bim excel write OUTPUT --data DATA [--sheet SHEET] [--pivot PIVOT] [--dry-run] [--yes]	Write JSON to an XLSX file. Data is supplied via the `data` param as inline JSON (NDJSON, JSON array of objects, or single JSON object) or a file path string. Columns are inferred from key union across all rows; first-seen order preserved. RFC3339/ISO-8601 date strings are stored as Excel date cells. bim-cli response envelopes ({"ok":true,"result":...}) are transparently unwrapped so piped driver output works without jq.
bim excel read FILE [--sheet SHEET] [--header-row N] [--map MAP] [--limit N]	Stream rows of an XLSX sheet as NDJSON (one JSON object per line). Date cells are emitted as RFC3339 strings in UTC unless BIM_EXCEL_TZ is set.
bim excel sheets FILE	List sheets in an XLSX file (NDJSON, one object per sheet).
bim excel info FILE	Inspect an XLSX file's schema without reading all data. Returns all sheets with column names, inferred types, and a sample value.
bim excel doctor	Check environment readiness. Returns JSON with ok field and per-check results.
bim excel version	Print driver version as JSON.

Write

bim excel write <output.xlsx> [--sheet Name] [--pivot Col] [--dry-run] [--yes]

Reads stdin: NDJSON (one JSON object per line), JSON array of objects, or a bim {ok,result} envelope (unwrapped automatically — pipe any bim command directly without jq).

• Columns are inferred from the key union across all rows. First-seen order preserved.
• RFC3339/ISO-8601 date strings are stored as Excel date cells and round-trip cleanly via read.
• --pivot Col adds a real Excel PivotTable on a second sheet named Pivot.
• --dry-run validates without writing; returns the same result shape with applied:false.
• --yes skips overwrite confirmation when the file already exists.
• Bare output names (no path separator) go to %TEMP%\bim-cli\out\<name>.xlsx. Cleaned after 24h.

Read

bim excel read <file.xlsx> [--sheet Name] [--header-row N] [--map Key=A,...] [--limit N]

Streams rows as NDJSON to stdout. Header row supplies keys.

• --header-row N — 1-based row index of the header row (default: 1).
• --map Mark=A,param=B,value=C — explicit column-letter-to-key mapping (overrides header row).
• --limit N — stop after N data rows (useful for sampling large files).
• Date cells are emitted as RFC3339 strings (UTC). Large integers (>2⁵³) are kept as strings.

Pipe compositions

# Revit schedule → Excel
bim revit schedule export "Door Schedule" | bim excel write doors.xlsx

# Excel params → Revit
bim excel read params.xlsx | bim revit param set --by Mark

# PDF takeoff → Excel pivot
bim pdf marked drawings.pdf | bim excel write takeoff.xlsx --pivot category

# Revit warnings → audit spreadsheet
bim revit warnings list | bim excel write audit.xlsx

# Site flood data → Excel report
bim site flood lookup --lat <f> --lon <f> | bim excel write flood-report.xlsx

Gotchas

• Column order matches the first object's key order in NDJSON input.
• Duplicate column names in an existing file are handled by appending a numeric suffix.
• read with no --sheet uses the first sheet in the workbook.
• Files in %TEMP%\bim-cli\out\ are cleaned after 24h. Use a full path for durable output.

For agent use: /excel/llms.txt