# bim-excel

> Read and write Excel files from the command line. The connective tissue between Revit schedules, site data, and spreadsheet-based AEC workflows.

## Verbs

```
bim excel write  <output.xlsx> [--sheet Name] [--pivot Col] [--dry-run] [--yes]
bim excel read   <file.xlsx>   [--sheet Name] [--header-row N] [--map Key=A,...] [--limit N]
bim excel sheets <file.xlsx>
bim excel info   <file.xlsx>
```

## write

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

- Columns inferred from key union across all rows; first-seen order preserved.
- RFC3339/ISO-8601 date strings stored as Excel date cells; round-trip cleanly via `read`.
- `--pivot Col` — adds a real Excel PivotTable on a `Pivot` sheet.
- `--dry-run` — validates without writing; returns same result shape with `applied:false`.
- `--yes` — skip overwrite confirmation when file already exists.
- Bare output names → `%TEMP%\bim-cli\out\<name>.xlsx` (24h TTL). Full paths used as-is.

Result: `{"ok":true,"result":{"path":"...","rows":N,"cols":N,"applied":true}}`

## read

Streams rows as NDJSON to stdout. Header row supplies keys. Date cells emitted as RFC3339 (UTC).

- `--header-row N` — 1-based row index of header (default: 1)
- `--map Mark=A,param=B,value=C` — explicit column-letter→key mapping (overrides header row)
- `--limit N` — stop after N data rows

## sheets / info

`sheets` — list all sheets: `{"name":"...","rows":N,"cols":N}` per line (NDJSON).

`info` — schema of each sheet: column names, inferred types (`string|number|boolean|date`), sample value from first data row.

## Pipe compositions

```
bim revit schedule export "Door Schedule" | bim excel write doors.xlsx
bim excel read params.xlsx | bim revit param set --by Mark
bim pdf marked drawings.pdf | bim excel write takeoff.xlsx --pivot category
bim revit warnings list | bim excel write audit.xlsx
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.
- `read` with no `--sheet` uses the first sheet in the workbook.
- `%TEMP%\bim-cli\out\` files cleaned after 24h; use a full path for durable output.
- Large integers (>2⁵³) are kept as strings to avoid precision loss.