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 export [--sheet N] [--all-sheets] [--bim] [--output DIR] |
export sheets to PDF; --bim writes 6 JSON sidecars (elements, marks, rooms, levels, properties, views) |
bim revit instances |
list all live sessions with pid, port, active document |
bim revit status [--detailed] |
running instance, model, port, add-in state; --detailed adds installation and version checks |
bim revit launch [--path MODEL] |
start Revit and wait for add-in; streams NDJSON progress |
bim revit kill [--pid PID] [--all] |
terminate one or all Revit instances and clean up registry entries |
bim revit open --path FILE |
open a .rvt in the running session |
bim revit install |
install the add-in DLL and manifest |
bim revit rvt-version <file> |
sniff saved-by version (no Revit needed) |
bim revit exec --code "C#" |
run C# against the live Revit API |
bim revit exec --file script.cs |
run a .cs file |
bim revit sheets list |
all sheets with number, name, and discipline |
bim revit schedule export <name> |
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 element-list --category <cat> [--level N] [--properties p1,p2] |
list non-type elements by category (OST_Walls or Walls); --level filters by name, --properties adds parameter columns |
bim revit schedule-read --name <schedule> |
read a named schedule — column headers + data rows as JSON |
bim revit material-query --name <material> |
material appearance: transparency, shininess, smoothness, RGB color, asset name |
bim revit param set --by Mark |
write parameters from stdin NDJSON |
bim revit location --id <eid> |
read each element's location point as {id, x, y, z} (read-only) |
bim revit move --id <eid> [--dx --dy --dz] |
translate elements by a vector in feet |
bim revit rotate --id <eid> --angle <deg> [--axis x|y|z] |
rotate elements about an axis (default z) through their location point |
bim revit view-activate --name <view> |
activate a named view (case-insensitive) |
bim revit pdf-view [--output PATH] |
export the active view to PDF |
bim revit model health |
aggregate model quality report |
bim revit purge [--dry-run] |
remove unused families, types, and views |
bim revit api search "query" |
search Revit API XML docs |
bim revit api type "Namespace.Class" |
all members of a type |
bim revit api describe "M:..." |
full docs for one member ID |
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: