# Command Reference

Use VentilatePro CLI commands for rooms, AHUs, Revit imports, calculations, and notes. Learn JSON output, pagination, and guarded writes.

Canonical: https://ventilatepro.com/exam/cli/commands/

Documentation version: VentilatePro CLI 0.8.4

## 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 status 41 --project 123 --wait` `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. The server writes the rooms in the background; confirm waits for it, and status reports progress. |
| 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 wait --project 123 --timeout 30` `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](https://ventilatepro.com/exam/cli/calculations/#cli-docs-content). |
| 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 note: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

```text
ventilatepro projects list
```

```text
ventilatepro projects show 123
```

Entities

```text
ventilatepro rooms list --project 123
```

```text
ventilatepro room-equipment summary --project 123
```

```text
ventilatepro zones list --project 123
```

```text
ventilatepro ahus list --project 123
```

```text
ventilatepro plants list --project 123
```

Systems

```text
ventilatepro systems hierarchy --project 123
```

```text
ventilatepro systems graph --project 123 --json
```

```text
ventilatepro systems topology --project 123
```

## Guarded workflow commands

Calculation commands

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

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

```text
ventilatepro calc steam --pressure 15 --pressure-units psig --load 1000000 --json
```

```text
ventilatepro calc status --project 123
```

```text
ventilatepro calc wait --project 123 --timeout 30
```

```text
ventilatepro calc ventilation --ahu 44
```

```text
ventilatepro calc recalculate-airflows --project 123
```

Design-day commands

```text
ventilatepro design-day context --project 123
```

```text
ventilatepro design-day run --project 123 --input design-day-request.json
```

```text
ventilatepro design-day results --job 987
```

Notes commands

```text
ventilatepro notes create --project 123 --body "Captured from terminal"
```

```text
ventilatepro notes list --project 123
```

```text
ventilatepro notes sync
```

Categorization commands

```text
ventilatepro categorization review --project 123 --output room-categorization.json
```

```text
ventilatepro categorization apply --project 123 --input room-categorization.json --yes
```

Revit import commands

```text
ventilatepro revit-imports review --project 123 --json
```

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

Meeting commands

```text
ventilatepro meetings context --project 123 --json
```

```text
ventilatepro meetings record --project 123 --input meeting.json --json
```

MCP commands

```text
ventilatepro mcp doctor
```

```text
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 `note:42` or `chilled-water:12`. |
| `--type`, `--source`, `--tags`, `--query` | `ventilatepro notes list --project 123 --kind meeting --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. |

```text
ventilatepro projects list --json
```

```text
ventilatepro calc status --project 123 --json
```

```text
ventilatepro notes list --project 123 --kind meeting --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` | `note`, `decision` | Restricts the list to notes or decisions; `--kind` narrows notes to meetings, calls, site visits, or agent sessions. |
| `--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. |

```text
ventilatepro notes list --project 123 --kind meeting --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.

```text
$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.