HVAC CLI Command Reference

Command Families

What ships in the public CLI today

Commands are grouped around the curated /api/cli/ surface. Use text mode for interactive terminal work and --json whenever another tool needs the stable response payload.

Family	Commands	Notes
Auth	`ventilatepro auth login` `ventilatepro auth status` `ventilatepro auth whoami` `ventilatepro auth logout`	Authenticate once, inspect the current identity, and clear local credentials.
Projects	`ventilatepro projects list` `ventilatepro projects show 123`	Discover accessible projects and inspect project counts and metadata.
Rooms	`ventilatepro rooms list --project 123` `ventilatepro rooms show 501`	Read room lists and detailed airflow-related room data.
Room equipment	`ventilatepro room-equipment list --project 123` `ventilatepro room-equipment summary --project 123` `ventilatepro room-equipment create --data '{"room": 501, "name": "Sterilizer", "heat_gain_value": 1.8, "heat_gain_unit": "KW"}'`	List, summarize, create, update, and explicitly delete equipment assigned to rooms.
Revit imports	`ventilatepro revit-imports review --project 123 --json` `ventilatepro revit-imports show 41 --project 123 --json` `ventilatepro revit-imports confirm 41 --project 123 --review-token <token-from-review> --yes` `ventilatepro revit-imports discard 41 --project 123 --yes`	Review staged room and zone changes, then confirm the exact unchanged revision with an explicit approval token.
Categorization	`ventilatepro categorization review --project 123 --output room-categorization.json` `ventilatepro categorization groups --project 123 --output room-groups.json` `ventilatepro categorization apply --project 123 --input room-categorization.json --yes`	Prepare deterministic review artifacts and apply confirmed, reasoned, stale-checked room categories.
Zones	`ventilatepro zones list --project 123` `ventilatepro zones show 27`	Read zone membership, airflow fields, and calculation status.
AHUs	`ventilatepro ahus list --project 123` `ventilatepro ahus show 44`	Inspect AHU identity, system type, airflow fields, and linked equipment.
Plants	`ventilatepro plants list --project 123` `ventilatepro plants show chilled-water:12`	Read plant summaries and typed plant detail payloads.
Systems	`ventilatepro systems hierarchy --project 123` `ventilatepro systems graph --project 123 --json` `ventilatepro systems topology --project 123`	Return structure for graphing, topology inspection, and downstream tooling.
Calc	`ventilatepro calc catalog` `ventilatepro calc psychrometrics --dry-bulb 75 --relative-humidity 50` `ventilatepro calc air-process --cfm 5000 --entering-dry-bulb 80 --entering-rh 50 --leaving-dry-bulb 55 --leaving-rh 95 --json` `ventilatepro calc steam --pressure 15 --pressure-units psig --load 1000000 --json` `ventilatepro calc status --project 123` `ventilatepro calc ventilation --ahu 44` `ventilatepro calc ahu-steps --ahu 44 --json` `ventilatepro calc ahu-properties --ahu 44 --procedure summer` `ventilatepro calc recalculate-airflows --project 123` `ventilatepro calc recalculate-stale --project 123 --scope zones --mode sync` `ventilatepro calc cav --ahu 44`	Offline engineering calculators require no login. Project reads and recalculation workflows use the authenticated API. See the calculation reference.
Design day	`ventilatepro design-day context --project 123` `ventilatepro design-day run --project 123 --input design-day-request.json` `ventilatepro design-day results --job 987`	Read readiness context, submit jobs, and retrieve results.
Notes	`ventilatepro notes create --project 123 --body "Captured from terminal"` `cat site-walk.md \| ventilatepro notes create --project 123 --stdin --tags field,urgent` `ventilatepro notes list --project 123` `ventilatepro notes show general-info:42 --project 123` `ventilatepro notes sync --project 123`	Capture CLI notes, search normalized note data, and retry queued note sync.
Meetings	`ventilatepro meetings context --project 123 --json` `ventilatepro meetings record --project 123 --input meeting.json --json` `ventilatepro meetings list --project 123`	Resolve project members and record minutes, decisions, and assigned tasks atomically.
MCP	`ventilatepro mcp doctor` `ventilatepro-mcp`	Validate and launch the local stdio server used by Codex, Claude, and other MCP clients.

Core read surface

Projects

ventilatepro projects list ventilatepro projects show 123

Entities

ventilatepro rooms list --project 123 ventilatepro room-equipment summary --project 123 ventilatepro zones list --project 123 ventilatepro ahus list --project 123 ventilatepro plants list --project 123

Systems

ventilatepro systems hierarchy --project 123 ventilatepro systems graph --project 123 --json ventilatepro systems topology --project 123

Guarded workflow commands

Calculation commands

ventilatepro calc psychrometrics --dry-bulb 75 --relative-humidity 50

ventilatepro calc air-process --cfm 5000 --entering-dry-bulb 80 --entering-rh 50 --leaving-dry-bulb 55 --leaving-rh 95 --json

ventilatepro calc steam --pressure 15 --pressure-units psig --load 1000000 --json ventilatepro calc status --project 123 ventilatepro calc ventilation --ahu 44 ventilatepro calc recalculate-airflows --project 123

Design-day commands

ventilatepro design-day context --project 123 ventilatepro design-day run --project 123 --input design-day-request.json ventilatepro design-day results --job 987

Notes commands

ventilatepro notes create --project 123 --body "Captured from terminal" ventilatepro notes list --project 123 ventilatepro notes sync

Categorization commands

ventilatepro categorization review --project 123 --output room-categorization.json ventilatepro categorization apply --project 123 --input room-categorization.json --yes

Revit import commands

ventilatepro revit-imports review --project 123 --json ventilatepro revit-imports confirm 41 --project 123 --review-token <token-from-review> --yes

Meeting commands

ventilatepro meetings context --project 123 --json ventilatepro meetings record --project 123 --input meeting.json --json

MCP commands

ventilatepro mcp doctor ventilatepro-mcp

Shared conventions

Convention	Where it shows up	Meaning
`--json`	Most read commands and note/auth flows	Prints the stable response payload directly for machine consumers.
`--project`	Project-scoped list, calc, design-day, and notes commands	Supplies the project ID that scopes the request.
`--limit` / `--offset`	List commands	Pagination over list endpoints that return `{count, limit, offset, results}`.
Typed references	`notes show`, `plants show`	Some detail commands take typed identifiers like `general-info:42` or `chilled-water:12`.
`--type`, `--source`, `--tags`, `--query`	`ventilatepro notes list --project 123 --type general-info --source cli --tags field,urgent --query terminal`	Filters the normalized notes list by type, origin, tags, and free text.
`--data` / `--input`	Equipment, categorization, meeting, and other write workflows	Accepts inline JSON or a JSON file/stdin payload for repeatable machine workflows.
`--yes` / MCP `confirm=true`	Apply, delete, run, import, export, and other consequential operations	Requires explicit caller confirmation before the guarded operation is sent.

ventilatepro projects list --json ventilatepro calc status --project 123 --json ventilatepro notes list --project 123 --type general-info --source cli --tags field,urgent --query terminal

Notes list flags

Notes keep the richest filter surface in the CLI today because they are the cross-model capture workflow. Use these flags when you need to find exactly the right note in a large project history.

Flag	Values	Behavior
`--project`	Project ID	Required for note list and note show reads.
`--limit`	1 to 100	Caps the number of notes returned.
`--offset`	0 or greater	Skips the first N matching notes.
`--type`	`general-info`, `design-minute`, `decision`	Restricts the list to a single normalized note type.
`--source`	`cli` or `web`	Filters by note origin.
`--tags`	Comma-separated tags	All listed tags must be present on the note.
`--query`	Free text	Searches note ref, title, body, tags, and metadata fields.
`--json`	Flag	Returns raw API-shaped JSON instead of human-readable lines.

ventilatepro notes list --project 123 --type general-info --source cli --tags field,urgent --query terminal

Write scripts that distinguish results from failures

Use --help at each command level to discover supported flags. Add --json only where supported. Check the process exit code before parsing results; JSON errors may be written to stdout as {"error": "message"}, while text errors normally use stderr. Do not infer success from nonempty output.

PowerShell example: read project data, stop on failure, then parse JSON. Project IDs in these docs are placeholders; replace them with IDs returned for your account.

$projectJson = ventilatepro projects list --limit 20 --offset 0 --json
if ($LASTEXITCODE -ne 0) { throw "VentilatePro project lookup failed" }
$projectPage = $projectJson | ConvertFrom-Json
$projectPage.results

For paginated lists, retain filters, increment offset by the returned row count, and continue until an empty page or the reported count is reached. A first page is not a complete project audit. Concurrent edits can change list contents; rerun the read if a consistent review is required.

Do not automatically retry every write after a timeout. The server may already have accepted it. Read the resulting record or job status first. Reuse the same idempotency key for the same notes or meeting operation; a new key can create another record. Idempotency is supported by specific operations, not every endpoint.

notes create can exit successfully after saving to the local queue. Check whether the result is created or queued before reporting that the server has the note. Follow up with notes sync and verify delivery.