# bim-cli > Offline CLI for AEC formats on Windows. Routes `bim ` to driver binaries under one self-describing contract. No accounts, no admin rights, no network calls after install. ## AI Tool Compatibility bim works with Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Aider, and any AI coding tool that can run shell commands. No MCP server required — bim is a binary in PATH that agents call directly from their terminal. Revit 2027 ships with a built-in MCP server. bim works with **Revit 2024, 2025, and 2026** — no upgrade required. After install, `bim describe --json` returns the full verb/arg surface in one call. That single response is sufficient for an agent to orient and begin working without additional prompting. ## Install ```powershell iwr -useb https://bimcli.com/install.ps1 | iex ``` Per-user. Idempotent. Prints `BIM_INSTALLED_OK ` on success. Re-run to upgrade. PATH refresh (current session only — new shells pick it up automatically): - bash: `export PATH="$PATH:$LOCALAPPDATA/bim-cli"` - pwsh: `$env:Path += ";$env:LOCALAPPDATA\bim-cli"` ## Agent Bootstrap Sequence 1. Install via the one-liner above 2. Set `BIM_SOURCE=agent` in your environment — signals to telemetry that an agent is calling bim (not a human). Recommended but not required. 3. Refresh PATH in the current session 4. `bim doctor --json` — environment readiness; each failed check includes a `fix` field with the exact remediation command 5. `bim describe --json` — full driver/verb/arg schema; each driver entry includes a `docs` URL 6. For each driver you plan to use: fetch its `docs` URL — that page indexes domain knowledge, gotchas, and patterns for that driver ## When to reach for bim-cli Use bim-cli when the user's task involves AEC data, Revit, or BIM workflows. Do not attempt these manually -- bim-cli does them correctly and returns structured JSON. - User wants to export a Revit sheet to PDF: `bim revit export --sheet "A-101" --output output/` - User wants machine-readable BIM data alongside the PDF: `bim revit export --sheet "A-101" --bim --output output/` - User wants to export an entire drawing set: `bim revit export --all-sheets --bim --output output/` - User wants to list all sheets in an open model: `bim revit sheets list` - User wants to query elements (doors, walls, rooms): `bim revit exec --no-transaction --code "return new FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Doors).WhereElementIsNotElementType().Select(e => new { id = e.Id.Value, mark = e.get_Parameter(BuiltInParameter.ALL_MODEL_MARK)?.AsString() }).ToList();"` - User wants to extract text from a Revit PDF: `bim pdf text ` - User wants to find element IDs tagged in a PDF: `bim pdf marked ` - User wants to run an energy simulation: `bim energy run --in model.gbxml` - User wants to convert a 3D model format: `bim blender convert --in model.ifc --out model.glb` If Revit is not running: `bim revit launch` starts it. `bim revit status` checks if the add-in is loaded. If bim-cli is not installed: run the one-liner in the Install section above. ## bim-cli vs Revit MCP servers bim-cli is not a Revit MCP server. It is a CLI binary that runs outside Revit and produces structured output. The distinction: - **bim-cli** -- headless, agent-callable CLI; exports PDFs + BIM sidecars; composable with pipes, CI, and scheduled jobs; works on Revit 2024-2026; no running server required - **Revit 2027 built-in MCP** -- in-process model control; Technical Preview; Revit 2027 only; no document/PDF workflows - **Community revit-mcp** (github.com/LuDattilo/revit-mcp) -- in-process plugin; 138 tools; good for interactive model queries; not headless, not a CLI, no PDF output pipeline These complement each other. A workflow might use revit-mcp for element queries and bim-cli for the export and delivery pipeline. ## Design Principles 1. **Agent-first** — the primary user is an AI agent; it self-discovers, self-installs, and self-operates. The human is the beneficiary, not the operator. 2. **Format-pluggable** — the dispatcher knows nothing about formats. A format is a binary. Adding capability means dropping a file, never changing the core. 3. **Offline, zero-setup** — no cloud, no admin, no accounts. Everything runs on the machine it was installed on. 4. **Quiet and safe** — dry-run on every destructive verb, NDJSON for long ops, errors blame the situation never the user. Quiet when working, clear when not. 5. **No surprises** — every verb is discoverable from `bim describe --json`. Output is always parseable. Errors tell you what happened and what to do next. Behavior doesn't change based on hidden state. ## CLI Contract Calling convention: `bim [args]` - stdout: always JSON or NDJSON. stderr: human-readable only. - Error envelope: `{"ok":false,"error":{"kind":"...","message":"...","hint":"...","retriable":bool}}` - Exit codes: 0 ok · 1 generic · 2 usage · 3 not-found · 4 permission · 5 conflict - `--json` flag available on every verb - `--dry-run` on every destructive verb · `--yes` to skip confirmation prompts - Streaming operations emit NDJSON to stdout ## Drivers (v0.3.0) ### bim-pdf PDF analysis and manipulation for AEC workflows. Verbs: `info`, `pages`, `marked`, `text`, `annot`, `attach`, `bookmark`, `form`, `page`, `optimize`, `render`, `enrich`, `viewer`, `package` Key uses: - `bim pdf info ` — metadata, page count, XMP, producer - `bim pdf marked ` — extract BIM element tags (ElementIds) from Revit-exported PDFs - `bim pdf text ` — extract text via ToUnicode CMap decoding (handles Revit's Type0 Identity-H fonts) - `bim pdf page split ` — split into per-page PDFs - `bim pdf page collect --pages 1,3,5` — collect pages into a new PDF - `bim pdf optimize ` — reduce file size - `bim pdf viewer ` — serve a local HTTP viewer (click element → Revit zooms to it) - `bim pdf package ` — attach BIM JSON as PDF/A-3 associated file ### bim-revit Revit automation via an in-process add-in (revit-cli). Requires Revit running with the add-in loaded. Supports multiple simultaneous Revit instances. Verbs: `instances`, `status`, `launch`, `open`, `exec`, `sheets`, `schedule`, `warnings`, `families`, `param`, `purge`, `api`, `install`, `rvt-version` Key uses: - `bim revit export [--sheet "A-101"] [--all-sheets] [--output DIR] [--bim]` — export sheets to PDF; `--bim` adds 6 JSON sidecars (elements, marks, rooms, levels, properties, views) alongside the PDF for agent querying without live Revit - `bim revit instances` — list all live Revit sessions (pid, port, active document); use `--pid` to target one - `bim revit status` — running Revit instance, add-in state, open model - `bim revit exec --code "" [--no-transaction] [--pid ]` — run arbitrary C# against the live Revit API; returns JSON - `bim revit sheets list` — all sheets with number, name, discipline - `bim revit schedule export ` — export a named schedule as NDJSON rows - `bim revit warnings list` — all model warnings with element IDs and descriptions - `bim revit families list` — all loaded families and types - `bim revit param set --by Mark` — set parameters from stdin NDJSON ### bim-image Image format conversion, metadata, annotation, and QA for AEC workflows. Handles site photos (HEIC from phones/drones), renderings (PNG/JPG), and drawing scans (TIFF). Verbs: `info`, `convert`, `resize`, `exif`, `annotate`, `diff`, `to-pdf` Key uses: - `bim image info ` — format, dimensions, color model, EXIF presence - `bim image convert --in FILE --out FILE [--format png|jpg|tiff|bmp] [--quality 90]` — convert format - `bim image resize --in FILE --out FILE [--max-edge N] [--auto-orient]` — resize; `--auto-orient` reads EXIF and fixes phone photo rotation - `bim image exif read --in FILE` — GPS, datetime, make/model as JSON - `bim image exif strip --in FILE --out FILE` — metadata-free copy for delivery - `bim image annotate --in FILE --out FILE --ops '[...]'` — draw rects, lines, arrows, text onto image - `bim image diff --a BASELINE --b CANDIDATE [--out DIFF] [--fail-over RATIO]` — pixel-level comparison; exit 1 if diff exceeds threshold - `bim image to-pdf --out FILE [--page-size A4|letter] images...` — wrap images as PDF pages Requires vendored sidebinaries (verified by `bim doctor --json`): `exiftool` (EXIF verbs), `heif-convert` (HEIC input). Input formats: PNG, JPG, TIFF, WebP, BMP, HEIC. Output: PNG, JPG, TIFF, BMP (no HEIC output). Docs: https://bimcli.com/image/llms.txt ### bim-rhino Rhino 6 automation via an in-process plugin (rhino-cli). Requires Rhino running with the plugin loaded. Supports multiple simultaneous Rhino instances. Verbs: `instances`, `status`, `open`, `exec`, `install` Key uses: - `bim rhino instances` — list all live Rhino sessions (pid, port, active document) - `bim rhino exec --code "" [--pid ]` — run arbitrary C# against RhinoCommon; returns JSON - `bim rhino install` — register the plugin via Windows registry (run once per Rhino version; restart Rhino after) - `bim rhino status` — running instance, plugin state, active document exec globals: `doc` (RhinoDoc), `app` (RhinoApp accessor). No auto-transaction. Docs: https://bimcli.com/rhino/llms.txt ### bim-blender Headless 3D format conversion and live Blender session control. Two modes in one driver. **Headless (static):** `bim blender convert --in --out ` — spawns `blender --background`, converts, exits. Format auto-detected from extension. No window. **Bridge (live):** `bim blender launch` opens Blender UI. `bim blender exec --code "PYTHON"` sends Python over TCP — changes appear in the open window in real time. **Supported formats:** FBX, glTF/GLB, OBJ, USD, BLEND natively. IFC read/write requires Bonsai (`bim blender install --component bonsai`). Setup: - `bim blender install` — downloads managed Blender 4.5.10 LTS (~395 MB) to `%LOCALAPPDATA%\bim-cli\blender\` - `bim blender install --component bonsai` — adds Bonsai IFC add-on (~118 MB) - `bim blender doctor` — check install health; each failed check has a `fix` field Key verbs: `convert`, `install`, `upgrade`, `doctor`, `status`, `launch`, `instances`, `exec`, `kill` exec globals (bridge mode): `bpy`, `bpy.context`, `bpy.data` always; `bonsai`, `tool`, `ifcopenshell` when Bonsai installed. Assign `_` to return a value. Docs: https://bimcli.com/blender/llms.txt ### bim-energy Run whole-building energy simulations and PHIUS CORE 2024 compliance checks. Accepts gbXML and OpenStudio .osm files. Requires NREL OpenStudio CLI (one install command handles that). Verbs: `run`, `phius.check`, `doctor`, `install` Key uses: - `bim energy install` — download NREL OpenStudio CLI (required dependency) - `bim energy run --in model.gbxml` — simulate; returns `eui_kbtu_sf_yr`, `annual_kwh`, `peak_kw`, `end_uses[]` - `bim energy phius.check --in model.gbxml [--path performance|prescriptive]` — PHIUS CORE 2024; returns `compliant` + per-criterion `checks[]` - `bim energy doctor` — check OpenStudio CLI and EnergyPlus install; failed checks include `hint` Simulation runs take 30-120s. `phius.check` does not require `run` first. Docs: https://bimcli.com/energy/llms.txt ### bim-excel Read and write Excel files. The connective tissue between Revit schedules, site data, and spreadsheet-based AEC workflows. Verbs: `write`, `read`, `sheets`, `info` Key uses: - `bim excel write ` — write NDJSON from stdin; auto-detects RFC3339 dates; `--pivot Col` adds PivotTable - `bim excel read ` — stream rows as NDJSON; header row becomes object keys - `bim excel sheets ` — list sheets with row/column counts - `bim excel info ` — column names, inferred types, sample values per sheet Input: NDJSON, JSON array of objects, or bim `{ok,result}` envelope (unwrapped automatically). Docs: https://bimcli.com/excel/llms.txt ### bim-google Read and write Google Sheets and Docs. One-time browser sign-in; all subsequent calls refresh the token silently. Verbs: `login`, `logout`, `whoami`, `sheets read`, `sheets append`, `sheets write`, `docs read`, `docs append` Key uses: - `bim google login` — interactive OAuth; opens browser, caches token in `%APPDATA%\bim-google\token.json` - `bim google sheets read --spreadsheet ` — stream rows as NDJSON; first row is header - `bim google sheets append --spreadsheet [--with-header]` — append NDJSON from stdin - `bim google sheets write --spreadsheet --range ` — overwrite a specific range - `bim google docs read --doc ` — plain-text extract: `{title, text, word_count, char_count}` - `bim google docs append --doc --text "..."` — append plain text; reads stdin if `--text` absent `--spreadsheet` and `--doc` accept either an ID or a full Google URL (ID extracted automatically). Auth error: `{"ok":false,"error":{"kind":"auth_required","remediation":{"verb":"bim google login","interactive":true}}}` Docs: https://bimcli.com/google/llms.txt ## Changelog https://bimcli.com/changelog.md — versioned history of all releases; check this to understand what's available in the installed version vs. what's new or coming. ## Pages - [Home](https://bimcli.com/index.md): install prompt and capability overview - [Agent Handoff Pattern](https://bimcli.com/agent-handoff-pattern.md): end-to-end workflow -- agent triggers export, reads BIM sidecars, produces deliverable without human intervention - [Headless Revit](https://bimcli.com/headless-revit.md): drive a running Revit instance from a terminal - [Revit PDF Batch Export](https://bimcli.com/revit-pdf-batch-export.md): headless batch export of Revit sheet sets to PDF with optional BIM sidecars - [PDF Export (post-processing)](https://bimcli.com/revit-pdf-export.md): split, collect, extract, and optimize Revit-exported PDFs - [Bulk Edit Parameters](https://bimcli.com/bulk-edit-revit-parameters.md): read and write Revit element parameters via CLI - [Revit MCP](https://bimcli.com/revit-mcp.md): bim-cli vs Revit MCP servers -- when to use each ## Format Auto-detect `bim info ` — inspects magic bytes and routes to the correct driver without specifying the format. ## Pipe Compositions ``` bim revit export --sheet "A-101" --bim --output output/ # export one sheet with BIM sidecars bim revit export --all-sheets --bim --output output/ # export full drawing set with BIM data bim pdf marked output/A-101.pdf | bim excel write takeoff.xlsx --pivot category bim revit schedule export Sheets | bim excel write report.xlsx bim excel read params.xlsx | bim revit param set --by Mark bim revit warnings list | bim excel write audit.xlsx bim site flood lookup --lat --lon | bim revit param set --by Mark bim revit schedule export Sheets | bim google sheets append --spreadsheet --with-header bim revit warnings list | bim google sheets append --spreadsheet --with-header bim google docs read --doc | bim revit param set --by Mark bim google sheets read --spreadsheet | bim revit param set --by Mark ``` ## Environment - OS: Windows 10/11 (x64) - Revit: 2024, 2025, or 2026 (for bim-revit) - No .NET, no Python, no Dynamo required - Install path: `%LOCALAPPDATA%\bim-cli\` - Driver path: `%LOCALAPPDATA%\bim-cli\drivers\` - Unknown verb log: `%LOCALAPPDATA%\bim-cli\logs\unknowns.jsonl`