CLI & MCP Troubleshooting

Authentication failures

If login fails immediately, verify the base URL and the copied token value.
If `auth whoami` fails after a previous login, the token may have been revoked or expired.
Use `ventilatepro auth logout` to clear local credentials, then log in again with a new token.
Revocation happens in the VentilatePro web UI, not from the CLI.

Project and note access

If `projects list` returns nothing, the authenticated user does not currently have access to any projects.
If `notes list` or `notes create` returns a project access error, confirm that the project ID belongs to the logged-in user or a shared project membership.
If `notes show` fails, verify both the `note_ref` and the `--project` argument.

MCP and AI-agent setup

Run ventilatepro mcp doctor before configuring the AI client. It checks login, Agent Editor scopes, catalog loading, and identity.
If doctor reports missing scopes, create a new Agent Editor token. Existing tokens are not silently expanded.
If the client cannot find ventilatepro-mcp, run where.exe ventilatepro-mcp on Windows or which ventilatepro-mcp on macOS/Linux and configure the full path.
After changing MCP configuration, restart or reconnect the client so it reloads the server catalog.
Keep the token out of MCP JSON. The local server reuses the credential saved by ventilatepro auth login.

Queue and sync behavior

Situation	Queued?	What to do
Network error	Yes	Run `ventilatepro notes sync` after connectivity returns.
Server 5xx	Yes	Retry later; the queued note keeps the same idempotency key.
Auth error	No	Fix credentials and rerun the command.
Validation error	No	Fix the command arguments or payload and rerun.

Exit behavior

`notes create` returns exit code 0 when the note is created immediately.
`notes create` also returns exit code 0 when the note is safely queued locally.
`notes create` returns non-zero for hard failures such as auth or validation problems.
`notes sync` returns non-zero when one or more queued notes still fail during the retry run.

Install and upgrade issues

Preferred install path: pipx install ventilatepro-cli
Preferred upgrade path: pipx upgrade ventilatepro-cli
Fallback install path when `pipx` is unavailable: python -m pip install ventilatepro-cli

Contact support

CLI and MCP failure recovery reference

Symptom	Check	Recovery
Executable not found	`where.exe ventilatepro-mcp` on Windows; `command -v ventilatepro-mcp` on macOS/Linux	Run `python -m pipx ensurepath`, reopen the terminal/client, or configure the absolute executable path. Escape Windows backslashes in JSON.
Local status says authenticated, but calls fail	`auth status` checks saved credentials; `auth whoami` makes a live request.	Verify the base URL, token validity, and account using `ventilatepro auth whoami`.
401 or OAuth reconnect required	Expired/revoked credentials or the wrong authentication mechanism	Reconnect OAuth for remote MCP; log in with a valid personal token for CLI/local project tools.
403 or missing scopes	Granted scopes and project membership	Use the appropriate token preset and verify project access. Doctor expects the full Agent Editor scope set; narrower access may be intentional.
404 for a record	Record ID, typed reference, project context, and permissions	Rediscover the record from an authorized list. Do not assume an inaccessible ID proves deletion.
Validation, confirmation, or stale-review error	Field errors, tool schema, current review revision	Correct inputs or fetch a fresh review. Inspect changes before confirming; do not blindly retry.
429, server failure, or network timeout	Rate-limit information, connectivity, and whether the operation was accepted	For reads, retry with bounded backoff and honor Retry-After when supplied. For writes, reconcile state or use the operation's existing idempotency key before retrying.
Local MCP works in terminal but fails in a desktop client	Executable path, OS user, config directory, and keyring availability	Run the client in the intended user context. `VENTILATEPRO_CONFIG_DIR` and `VENTILATEPRO_DATA_DIR` override local paths; they are not independent keyring identities.

For a support request, include the package version from pipx list, operating system, client name, sanitized command, error, and whether an offline calculator succeeds. Doctor output can include your identity; redact personal and project data before sharing. Never send tokens, Authorization headers, or config.json.