# Install the CLI

Install VentilatePro CLI with pipx, run your first offline calculation, authenticate for project work, and choose suitable token scopes.

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

Documentation version: VentilatePro CLI 0.7.0

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.

1. Install the CLI

   Use `pipx` on workstations when possible. It keeps the tool isolated and makes upgrades predictable.

   ```text
   pipx install ventilatepro-cli
   ```

   ```text
   pipx upgrade ventilatepro-cli
   ```
2. 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](https://ventilatepro.com/hvac/?view=account-settings)
   [Token presets](https://ventilatepro.com/exam/cli/install/#token-presets)
3. 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.

   ```text
   ventilatepro auth login
   ```

   ```text
   Get-Clipboard | ventilatepro auth login --token-stdin
   ```
4. 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.

   ```text
   ventilatepro auth whoami
   ```

   ```text
   ventilatepro projects list
   ```
5. 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.

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

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

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

   ```text
   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](https://ventilatepro.com/exam/cli/commands/) or [MCP setup](https://ventilatepro.com/exam/cli/mcp/).