VentilatePro CLI

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

Install

Published releases install from PyPI:

pipx install ventilatepro-cli

Upgrade an existing install:

pipx upgrade ventilatepro-cli

Local development install:

cd ventilatepro-cli
pip install -e .

Commands

ventilatepro auth login
ventilatepro projects list
ventilatepro projects show 1
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 systems hierarchy --project 1
ventilatepro calc status --project 1
ventilatepro calc ahu-properties --ahu 1
ventilatepro design-day context --project 1
ventilatepro notes create --project 1 --body "Captured from terminal"
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 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.

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

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

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:

ventilatepro mcp doctor

4. Add the stdio server to Codex:

codex mcp add ventilatepro -- ventilatepro-mcp

For JSON-based MCP clients, use:

{
  "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:

ventilatepro auth login --token-prompt-visible

or pipe the token through stdin:

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

See the hosted install guide at https://ventilatepro.com/exam/cli/, plus docs/commands.md, docs/auth.md, docs/api.md, and docs/releasing.md in this repo.