Metadata-Version: 2.4
Name: ventilatepro-cli
Version: 0.8.1
Summary: HVAC engineering CLI and Model Context Protocol (MCP) server: psychrometrics, cooling and heating loads, hydronics, steam, fan and pump power, duct sizing, and scoped VentilatePro project automation for scripts and AI agents
Project-URL: Homepage, https://ventilatepro.com/
Project-URL: Documentation, https://ventilatepro.com/exam/cli/
Project-URL: HVAC calculations, https://ventilatepro.com/exam/cli/calculations/
Project-URL: MCP server setup, https://ventilatepro.com/exam/cli/mcp/
Project-URL: Psychrometric calculator, https://ventilatepro.com/tools/psychrometric-calculator/
Project-URL: Changelog, https://ventilatepro.com/changelog/
Project-URL: Repository, https://github.com/Rushikeshh-patil/PE-Exam
Project-URL: Support, https://ventilatepro.com/exam/support/
Keywords: hvac,hvac-design,psychrometrics,psychrometric-calculator,cooling-load,heating-load,ventilation,ashrae,hydronics,chilled-water,steam,duct-sizing,fan-power,pump-power,mechanical-engineering,building-services,revit,equipment-schedule,mcp,mcp-server,model-context-protocol,ai-agent,claude,chatgpt,codex,copilot,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.16.0
Requires-Dist: requests>=2.32.0
Requires-Dist: keyring>=25.6.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: mcp<2.0.0,>=1.30.0
Requires-Dist: PsychroLib==2.5.0
Requires-Dist: CoolProp==8.0.0

# VentilatePro CLI

The plumbing identity foundation supports explicit Revit model registrations,
reviewed mappings to existing rooms, and read-only fixture scan previews.
Start with `ventilatepro schemas show revit_identity --json` and
`ventilatepro revit-identity catalog --project 4 --json`.
See [identity commands](docs/commands.md#revit-identity-and-plumbing-payload-preview).
Fixture persistence, Revit extraction and the plumbing web workspace follow in
later increments.

Pump head worksheets can be inspected with
`ventilatepro equipment show hydronic-pumps 7 --json` and saved with
`ventilatepro equipment update hydronic-pumps 7 --input pump-head.json --json`.
See [pump head commands](docs/commands.md#pump-head) for a payload example;
saving recalculates the head used by equipment schedules.

The ChatGPT sidebar workspace at `https://ventilatepro.com/mcp/workspace`
includes a Home tab with calculator and saved-result workflows, documentation
links, and prompt examples that can start a chat on supported hosts.
See the [workspace guide](https://ventilatepro.com/exam/cli/mcp/#chatgpt-workspace).

The engineering plugin at `https://ventilatepro.com/mcp` supports preparing,
running and reporting Revit-based room load calculations, with typed tools and
the same scoped backend as the web app. Existing read-only workspace grants
stay read-only; reconnect after deployment for engineering access.

```bash
ventilatepro design-day prepare --project 1 --json > load-review.json
```

Review readiness and assumptions, then submit the returned `request` with
`--revision <source_revision> --signature <input_signature>`. Poll
`design-day status --job <id>`, read `design-day results --job <id> --json`, and
save `design-day report --job <id> --output loads.csv`. See
[design-day commands](docs/commands.md#design-day) for options and scopes.
These are preliminary EnergyPlus room loads; equipment sizing and Title 24
compliance are unavailable.

VentilatePro CLI is a local command-line client for authenticating to VentilatePro, recording project notes and meeting minutes, and running scoped engineering workflows.

It also includes offline HVAC calculations for PsychroLib-based psychrometrics,
sensible and total air loads, complete air-process balances, hydronics,
IAPWS-IF97 saturated steam through CoolProp 8.0.0, fan and pump power, duct sizing, and LMTD. Local
calculations require no login and are also available as typed MCP tools.

MCP Registry: `com.ventilatepro/ventilatepro` (this line also verifies PyPI package ownership for the registry).

<!-- mcp-name: com.ventilatepro/ventilatepro -->

Public documentation: [CLI quick start](https://ventilatepro.com/exam/cli/), [HVAC calculation reference](https://ventilatepro.com/exam/cli/calculations/), and [MCP setup and tool discovery](https://ventilatepro.com/exam/cli/mcp/). Local integration details: [MCP guide](docs/mcp.md). Python 3.10 or newer is required.

## Install

Published releases install from PyPI:

```bash
pipx install ventilatepro-cli
```

Upgrade an existing install:

```bash
pipx upgrade ventilatepro-cli
```

Local development install:

```bash
cd ventilatepro-cli
pip install -e .
```

## Commands

```bash
ventilatepro auth login
ventilatepro projects list
ventilatepro projects show 1
ventilatepro projects update 1 --scope-of-work "Replace AHU-1; exclude central plant work."
ventilatepro memory context --project 1 --json
ventilatepro rooms list --project 1
ventilatepro room-equipment summary --project 1
ventilatepro room-equipment create --data '{"room": 501, "name": "Sterilizer", "heat_gain_value": 1.8, "heat_gain_unit": "KW"}'
ventilatepro revit-imports review --project 1 --json
ventilatepro revit-imports confirm 41 --project 1 --review-token <token-from-review> --yes
ventilatepro categorization review --project 1 --output room-categorization.json
ventilatepro categorization apply --project 1 --input room-categorization.json --yes
ventilatepro ahus list --project 1
ventilatepro controls drawing catalog --project 1 --json
ventilatepro controls drawing get --package 9 --json
ventilatepro controls drawing export --package 9 --format dxf --output AHU-1-controls.dxf
ventilatepro schedules fields air_handling_unit_schedule
ventilatepro schedules set air_handling_unit_schedule AHU-1 --project 1 --set basis_of_design_manufacturer_and_model="Trane CSAA012"
ventilatepro schedules add-remark air_handling_unit_schedule --project 1 --text "PROVIDE WITH FACTORY-MOUNTED DISCONNECT."
ventilatepro schedules set air_handling_unit_schedule AHU-1 --project 1 --remarks 1
ventilatepro bug-reports list
ventilatepro bug-reports resolve 12 --note "Fixed in #130"
ventilatepro systems hierarchy --project 1
ventilatepro calc status --project 1
ventilatepro calc ahu-properties --ahu 1
ventilatepro calc psychrometrics --dry-bulb 75 --relative-humidity 50 --json
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 fan-power --cfm 20000 --static-pressure 4 --fan-efficiency 0.68 --motor-efficiency 0.92
ventilatepro design-day context --project 1
ventilatepro notes create --project 1 --body "Captured from terminal"
ventilatepro notes create --project 1 --kind site_visit --title "Level 2 ceiling walk" --body "Corridor 204 is tight"
ventilatepro notes list --project 1 --pinned
ventilatepro memory playbook
ventilatepro memory context --project 1
ventilatepro memory search "HHW delta T" --project 1
ventilatepro memory log --project 1 --summary "Reviewed pump selections" --fact "CHWP-2 is 40 GPM short" --used note:12
ventilatepro memory review --project 1
ventilatepro memory curate retitle note:14 --project 1 --title "Roof hatch size" --reason "Title was vague"
ventilatepro notes sync
ventilatepro meetings context --project 1 --json
ventilatepro meetings record --project 1 --input meeting.json --json
ventilatepro meetings list --project 1
ventilatepro decisions create --project 1 --text "Use heat recovery on AHU-2" --reason "Energy model payback" --tags ahu,energy
ventilatepro decisions list --project 1
ventilatepro decisions revise 51 --text "Use heat recovery with bypass control"
ventilatepro tasks context --project 1 --json
ventilatepro tasks create --project 1 --description "Issue updated duct plan" --assignee-id 12 --priority high
ventilatepro tasks list --assignee me --status open,in_progress --due overdue
ventilatepro tasks update 46 --status done
ventilatepro tasks bulk 46 47 --due-at 2026-10-05
ventilatepro tasks comment 46 --text "Sent to the architect for review"
ventilatepro reviews start --project 1 --drawing M-set.pdf --spec div23.pdf --codes "IMC 2024" --phase CD --wait
ventilatepro reviews findings --review <review-id> --severity critical,major
ventilatepro reviews report --review <review-id> --as csv --output findings.csv
ventilatepro mcp doctor
ventilatepro-mcp
```

`ventilatepro-mcp` starts the local stdio MCP server for Codex, Claude Desktop,
and other MCP clients. It uses the same saved base URL and CLI token created by
`ventilatepro auth login`. The package-named `ventilatepro-cli` executable does the
same thing, so `uvx ventilatepro-cli` or `pipx run ventilatepro-cli` starts the
server with no install step. The remote streamable-HTTP endpoint at
`https://ventilatepro.com/mcp` uses OAuth instead of a token.

Local HVAC tools (`vp_calculate_psychrometrics`,
`vp_calculate_air_process`, `vp_calculate_steam`, and the rest of the catalog)
do not use that login or make network requests.

For meeting capture, Codex first reads `meetings context` to resolve names to
stable project-member IDs, interprets the PM's prose into a structured JSON
payload, and calls `meetings record`. The server atomically creates the meeting,
decisions, and assigned project tasks and returns a direct web-app link.

For standalone work, Codex reads `tasks context` to resolve an assignee to a
stable project-member user ID, then calls `tasks create`. The same workflow is
available through the typed `vp_get_task_context` and
`vp_create_project_task` MCP tools.

Design decisions do not require meeting minutes. Codex can call `decisions
create` or `vp_create_decision` as soon as a PM communicates a decision, with
an optional meeting ID only when the relationship is useful. Listing, showing,
and revising decisions are available through first-class CLI and MCP surfaces;
revisions preserve the prior version as immutable history.

For room classification, Codex can read the project-specific categorization
review resource or use the dedicated MCP tools. Review manifests default every
room to rejected so ambiguous spaces remain visible until a category is
explicitly accepted with a reason.

For staged Revit imports, agents use `revit-imports review` or
`vp_review_revit_import` first. The returned review token identifies the exact
payload and diff that was inspected. Confirmation requires that unchanged token
plus explicit `--yes` or MCP `confirm=true`; stale reviews are rejected.

## MCP setup

### ChatGPT web

Create a custom ChatGPT plugin with OAuth authentication and use this complete
server URL:

```text
https://ventilatepro.com/mcp
```

ChatGPT discovers VentilatePro's OAuth 2.1 metadata automatically. Sign in to
VentilatePro and approve the requested scopes; do not create or paste a CLI token
into ChatGPT. The flow uses authorization code + S256 PKCE, short-lived access
tokens, rotating refresh tokens, and exact ChatGPT callback validation.

### Local stdio clients

1. In the VentilatePro web app, open Account Settings and create a CLI token with
   the `Agent Editor` preset.
2. Log in locally:

```bash
ventilatepro auth login --token vpcli_...
```

The production URL defaults to `https://ventilatepro.com`. Use `--url` only for
local development, staging, or self-hosted VentilatePro servers.

3. Confirm the local setup:

```bash
ventilatepro mcp doctor
```

4. Add the stdio server to Codex:

```bash
codex mcp add ventilatepro -- ventilatepro-mcp
```

For JSON-based MCP clients, use:

```json
{
  "mcpServers": {
    "ventilatepro": {
      "command": "ventilatepro-mcp",
      "args": []
    }
  }
}
```

If the client cannot find `ventilatepro-mcp`, run `where ventilatepro-mcp` on
Windows or `which ventilatepro-mcp` on macOS/Linux and use the full path as the
command.

If the hidden token prompt is awkward in your terminal, use either:

```bash
ventilatepro auth login --token-prompt-visible
```

or pipe the token through stdin:

```bash
printf '%s' "$VPCLI_TOKEN" | ventilatepro auth login --token-stdin
```

See the hosted install guide at `https://ventilatepro.com/exam/cli/`, the HVAC
calculation reference at `https://ventilatepro.com/exam/cli/calculations/`, the
machine-readable index at `https://ventilatepro.com/llms.txt`, plus
[docs/commands.md](./docs/commands.md), [docs/auth.md](./docs/auth.md),
[docs/api.md](./docs/api.md), and [docs/releasing.md](./docs/releasing.md) in this repo.

Read Revit geometry with `ventilatepro air-distribution geometry ROOM_ID --json`; list availability with `ventilatepro air-distribution rooms --project PROJECT_ID --json`. See [Air Distribution commands](docs/commands.md#air-distribution-geometry).


Air Distribution now supports ceiling grids, terminal placement, project product editing,
and reviewed supply-layout proposals through both CLI and MCP. Start with
`vp air-distribution editor layout get --room ID --json`; see
[editor commands](docs/commands.md#air-distribution-m2-ceiling-plans-and-terminals).

Analyse a layout with `vp air-distribution analysis run --room ID --fidelity SIMPLE --json`
(ASHRAE throw/ADPI, immediate) or `--fidelity FFD --yes --wait` (fast fluid dynamics,
minutes), then read slices with `vp air-distribution analysis field --room ID --run RUN_ID`.
MCP agents use `vp_air_distribution_analysis`; see
[analysis commands](docs/commands.md#air-distribution-analysis-simple-adpi-ffd-openfoam).

Plumbing: `ventilatepro plumbing show --project ID --json` opens the shared fixture/system inventory. Use `schemas show plumbing` to discover reviewed import, CPC calculation, network adoption and report workflows. See [commands](docs/commands.md#plumbing-workspace-2025-california-plumbing-code).
