Drive a running Revit session from the command line. Export sheets to PDF with BIM sidecars, read schedules, write parameters across hundreds of elements, list model warnings, run arbitrary code against the open document. The kind of work that takes a half-hour for someone fluent in visual scripting, and a full afternoon by hand.
Revit automation via an in-process add-in. Every command is a JSON request over localhost — no keyboard, no mouse, no Revit window in focus required.
Requires: Revit 2024, 2025, or 2026 running with the revit-cli add-in loaded. Run bim revit install once to register the add-in, then restart Revit.
The revit-cli add-in binds to a dynamic port at startup and writes it to %LOCALAPPDATA%\bim-cli\instances\revit-<pid>.json. bim-revit reads that file, sends JSON requests, and the add-in executes them in Revit's main thread. Multiple Revit instances are supported — use bim revit instances to list them and --pid to target one.
These variables are pre-injected into every bim revit exec snippet:
| Variable | Type | Available when |
|---|---|---|
uiApp |
Autodesk.Revit.UI.UIApplication |
always |
app |
Autodesk.Revit.ApplicationServices.Application |
always |
doc |
Autodesk.Revit.DB.Document |
when a document is open |
uiDoc |
Autodesk.Revit.UI.UIDocument |
when a document is open |
linkedDocs |
IEnumerable<Document> |
when a document is open |
allDocs |
IEnumerable<Document> |
when a document is open (active + linked) |
failuresPreprocessor |
BimFailuresPreprocessor |
when --failures is set |
Common namespaces available without import: Autodesk.Revit.DB, Autodesk.Revit.UI, System.Linq, System.Collections.Generic. See namespace reference for the full list.
Revit scripts that batch element edits frequently encounter failures (warnings or errors) that would
otherwise pop a modal dialog and block headless execution. The --failures flag installs a
failure preprocessor that handles these automatically:
bim revit exec --failures delete-warnings --code "..."
bim revit exec --failures rollback --code "..."
delete-warnings suppresses all warning-level failures and lets the transaction commit normally.
rollback additionally rolls back the transaction when any error-level failure occurs.
When your script does not open its own Transaction, bim-cli wraps it in one automatically. With
--failures set, that wrapper transaction gets the preprocessor installed:
bim revit exec --failures rollback --code "
// This code runs inside a Transaction that has failuresPreprocessor installed.
// If Revit raises an error, the transaction rolls back automatically.
var wall = new FilteredElementCollector(doc)
.OfClass(typeof(Wall))
.FirstElement() as Wall;
wall.Name = \"Renamed\";
return failuresPreprocessor.Messages;
"
The result is the list of failure messages collected by the preprocessor (empty on success). The exit code is non-zero if the transaction was rolled back.
When your script opens its own Transaction (detected automatically from the source, or when
--no-transaction is set), bim-cli injects the BimFailuresPreprocessor class and a
failuresPreprocessor variable without wrapping the transaction. Attach it to your transaction
via SetFailuresPreprocessor:
// Run with: bim revit exec --failures rollback --no-transaction --file script.cs
var tx = new Transaction(doc, "batch-edit");
tx.GetFailureHandlingOptions()
.SetFailuresPreprocessor(failuresPreprocessor); // attach before Start()
tx.Start();
// ... batch edits ...
tx.Commit();
return new {
committed = tx.GetStatus() == TransactionStatus.Committed,
warnings = failuresPreprocessor.Messages,
};
failuresPreprocessor.Messages collects all failure descriptions seen during the transaction,
whether or not the transaction committed. This lets callers report failures without losing the
return value.
Omitting --failures leaves all transaction behavior unchanged from the default: failures surface
as Revit dialogs (blocked in headless sessions) and the preprocessor variable is not injected.
| Verb | What it does |
|---|---|
bim revit exec [--code CODE] [--file FILE] [--no-transaction] [--allow-no-doc] [--timeout N] [--launch-timeout N] [--kill-on-launch-timeout] [--path FILE] [--revit-version N] [--pid N] [--compile-only] [--args-json ARGS-JSON] [--mock] [--failures FAILURES] | Execute arbitrary C# against the Revit API. Launches Revit automatically if not running. |
bim revit quit [--pid N] [--all] [--idle N] | Close a Revit instance. Auto-selects when exactly one instance is running. |
bim revit kill [--pid N] [--all] [--idle N] | Terminate one or all registered Revit instances (alias for quit) |
bim revit instances | List all live Revit instances |
bim revit open --path FILE [--detached] [--timeout N] [--mode MODE] [--launch-timeout N] [--kill-on-launch-timeout] [--revit-version N] [--pid N] [--activate] [--close-others] [--discard] | Open a .rvt file in the active Revit instance |
bim revit launch [--path FILE] [--new] [--max N] [--timeout N] [--kill-on-launch-timeout] [--revit-version N] [--wait-for-addon N] | Launch Revit and wait for the add-in to come up |
bim revit status [--detailed] [--revit-version N] [--pid N] | Revit + add-in state |
bim revit install [--all] [--revit-version N] | Extract the add-in DLL and write the .addin manifest |
bim revit rvt-version --file FILE | Sniff the Revit version a .rvt was saved by (no Revit required) |
bim revit export [--all-sheets] [--sheet-set SHEET-SET] [--sheet SHEET] [--sheets SHEETS] [--active-view] [--output FILE] [--paper-size PAPER-SIZE] [--orientation ORIENTATION] [--color COLOR] [--raster-quality RASTER-QUALITY] [--name-by NAME-BY] [--name-pattern NAME-PATTERN] [--per-sheet] [--bim] [--sidecars SIDECARS] [--no-bim] [--no-pack] [--timeout N] [--revit-version N] [--pid N] [--mock] [--preflight] | Export sheets as PDF (mirrors Revit Export PDF dialog). With BIM options (default), embeds element/mark/scale/level/annotation/titleblock sidecars as a PDF-BIM package. |
bim revit doctor | Driver health check |
bim revit version | Driver version |
bim revit model | Model-level queries. Requires a subverb. |
bim revit coords [--revit-version N] [--pid N] [--mock] | Report the active document's positional reference systems: internal origin, project base point, survey point, deltas, site location, and named project locations. Read-only; requires a model open. |
bim revit export-views --filter FILTER --output FILE [--format FORMAT] [--revit-version N] [--pid N] | Export matching sheets as PDF using a name-filter regex. Alias over exec -- no Revit Transaction required. |
bim revit alias | Manage and discover exec alias scripts (builtin + user-tier from scripts dir). |
bim revit sheet-list [--revit-version N] [--pid N] | List all non-placeholder sheets (number, name). No Revit transaction. |
bim revit warnings-export [--revit-version N] [--pid N] | Export all Revit model warnings (description, severity, failing element IDs). No Revit transaction. |
bim revit linked-models [--revit-version N] [--pid N] | List all linked Revit models (name, path, loaded status). No Revit transaction. |
bim revit param-dump --category CATEGORY [--revit-version N] [--pid N] | Dump parameter names, storage types, and values for the first element in a BuiltInCategory. No Revit transaction. |
bim revit export-sheets --sheets SHEETS --output FILE [--revit-version N] [--pid N] | Export a comma-separated set of sheet numbers to PDF. Requires an open Revit document. |
bim revit rotate --id ID --angle ANGLE [--axis AXIS] [--revit-version N] [--pid N] | Rotate one or more elements about an axis through each element's location point. Requires a Revit transaction. |
bim revit move --id ID [--dx DX] [--dy DY] [--dz DZ] [--revit-version N] [--pid N] | Translate one or more elements by a vector (feet). Requires a Revit transaction. |
bim revit location --id ID [--revit-version N] [--pid N] | Read the LocationPoint of one or more elements (x, y, z in feet). No Revit transaction. |
bim revit pdf-view [--output FILE] [--revit-version N] [--pid N] | Export the active view to PDF (PDFExportOptions). Prints the written path. |
bim revit view-activate --name NAME [--revit-version N] [--pid N] | Activate a view by name (sets uidoc.ActiveView). No Revit transaction. |
bim revit element-list --category CATEGORY [--level LEVEL] [--properties PROPERTIES] [--revit-version N] [--pid N] | List elements by BuiltInCategory or display name; optional level filter and extra property columns. No Revit transaction. |
bim revit schedule-read --name NAME [--revit-version N] [--pid N] | Read a named ViewSchedule and return its rows as JSON. No Revit transaction. |
bim revit material-query --name NAME [--revit-version N] [--pid N] | Query a material's appearance asset properties (color, shininess, transparency, smoothness, asset name). No Revit transaction. |
bim revit save [--revit-version N] [--pid N] [--timeout N] | Save the active Revit document. Returns the saved file path. |
bim revit export-image --views VIEWS --out FILE [--px N] [--fit] [--revit-version N] [--pid N] [--timeout N] | Export named views to PNG files. Unknown view names produce a per-view error without failing the entire batch. |
For agent use: /revit/llms.txt
Task-focused walkthroughs for the most common Revit jobs — each with a copy-paste agent prompt and exact commands: