Installation

Prerequisites

Requirement	Notes
Python	>= 3.12
uv	Recommended for local development and running the CLI from source

Install from PyPI

uv tool install pbi-agent

WARNING

If this is your first uv tool install, reload your shell before running pbi-agent or the command may not be on your PATH yet.

To update an existing installation later, run:

uv tool upgrade pbi-agent

Install from Source

git clone https://github.com/pbi-agent/pbi-agent.git
cd pbi-agent
uv sync

Verify the Install

uv run pbi-agent --help

If you installed the package with uv tool install, you can also verify it with pbi-agent --help.

Quick Start

Set an API key, then run the browser UI or a single prompt:

export PBI_AGENT_API_KEY="sk-..."
uv run pbi-agent

uv run pbi-agent run --prompt "Summarize this repository and identify the main moving parts."

TIP

Startup loads environment variables from a local .env file automatically through python-dotenv, so you can keep PBI_AGENT_API_KEY, PBI_AGENT_PROVIDER, and related settings there.

Alternative: Connect a ChatGPT Subscription

For OpenAI, you can save a provider that uses a ChatGPT account session instead of an API key.

uv run pbi-agent config providers create \
  --name "OpenAI ChatGPT" \
  --kind openai \
  --auth-mode chatgpt_account

uv run pbi-agent config profiles create \
  --name chatgpt \
  --provider-id openai-chatgpt \
  --model gpt-5.4

uv run pbi-agent config providers auth-login openai-chatgpt
uv run pbi-agent config profiles select chatgpt
uv run pbi-agent

auth-login opens the browser flow by default. Use --method device for the device-code fallback. The full saved-provider workflow, including the equivalent Settings-page flow in the web UI, is documented in Providers.