Python 3.10 or newer is required. Local calculators work without a VentilatePro account after installation.

Get from zero to a working CLI session in five steps#

The CLI is distributed through PyPI as ventilatepro-cli. It uses the VentilatePro web app for token issuance, then talks only to the stable /api/cli/ surface.

Install the CLI
Use pipx on workstations when possible. It keeps the tool isolated and makes upgrades predictable.
```
pipx install ventilatepro-cli
```
```
pipx upgrade ventilatepro-cli
```
Create a CLI token in VentilatePro
Open Account Settings, choose the preset that matches your workflow, create the token, and copy the raw token immediately. The raw secret is shown once.

Create a CLI token Token presets
Log in from the terminal
The CLI validates the token before saving it. Use the default flow if you want the hidden prompt, or pipe the token from stdin for scripted setups.
```
ventilatepro auth login
```
```
Get-Clipboard | ventilatepro auth login --token-stdin
```
Confirm the session and discover a project
Check that the stored token resolves to the expected user, then list accessible projects and capture the project ID you want to work with.
```
ventilatepro auth whoami
```
```
ventilatepro projects list
```
Run the first useful command
From here you can inspect project data, model room equipment, run supported calculations, capture notes, or connect an MCP agent depending on the token preset you created.
```
ventilatepro rooms list --project 123
```
```
ventilatepro room-equipment summary --project 123
```
```
ventilatepro calc status --project 123
```
```
ventilatepro mcp doctor
```

Preferred install paths#

Use case	Command	Notes
Recommended workstation install	`pipx install ventilatepro-cli`	Isolated CLI install with straightforward upgrades.
Version-pinned install	`pipx install ventilatepro-cli==0.7.0`	Useful for repeatable onboarding or internal docs.
Upgrade existing install	`pipx upgrade ventilatepro-cli`	Pulls the newest published version from PyPI.
Fallback if `pipx` is unavailable	`python -m pip install ventilatepro-cli`	Use inside a virtual environment instead of the global interpreter.

Choose the smallest preset that matches the job#

VentilatePro issues CLI tokens from the web UI. The preset determines which command families work from the terminal. Existing note tokens are not silently upgraded.

Preset	Use it for	Enabled command families
`notes-only`	Field capture, note review, and sync.	`projects` discovery plus `notes`.
`assistant-read-calc`	Shell use and external AI tooling that needs read access plus approved calculation endpoints.	`projects`, `rooms`, `zones`, `ahus`, `plants`, `systems`, `calc`, and `design-day`.
`editor`	Human-operated model editing from the terminal.	Read, calculations, notes, entity writes, imports, schedules, and controls.
`agent-editor`	Codex, Claude, and other local MCP agents that need guarded full-workflow access.	Editor capabilities plus QC, notifications, exports, team lookup, and MCP confirmation guardrails.

Continue with the command reference or MCP setup.