# brewbar — Usage Manual

[English](USAGE.md) · [中文](USAGE.zh.md)

This guide walks through every part of the brewbar UI. For installation see the [README](../README.md).

## Getting started

Run `bunx brewbar` (or `brewbar` if installed globally). brewbar opens your browser at a URL like `http://127.0.0.1:4321/?token=…`. The `token` authorizes this session and changes every launch — use the tab brewbar opened, or copy the printed URL. Press `Ctrl-C` in the terminal to stop the server.

If Homebrew isn't installed, you'll see an onboarding screen first; install Homebrew, then reload.

## Core concepts

### Providers

A **provider** is a package manager. Homebrew is the default; the **provider switcher** (the pill row near the top of Installed / Updates / Discover / Security) lets you switch to any other detected manager: npm, pip, cargo, go, gem, bun, pnpm. Each provider's "scope" (e.g. *Global npm packages*) and source/registry are shown where relevant.

### Command preview

Whenever you trigger an action (install, upgrade, uninstall, tap, …) a dialog shows the **exact command** brewbar will run, with the destructive/interactive flags called out. Nothing runs until you confirm — and what you confirm is exactly what executes. You can also choose **Dry run** where the underlying tool supports it.

### The Activity dock & terminal

The bar pinned at the bottom is the **Activity** dock. Click it to expand a real terminal (xterm.js) plus the **operation queue**. Jobs stream their output live; if a command asks for your password (`sudo`) or a `[Y/n]` confirmation, type directly into the terminal. From the queue you can cancel running jobs and retry failed ones. The **History** link opens a persistent log of past operations.

### Command palette

Press `⌘K` (Cmd-K) anywhere to open a fuzzy command palette for quick navigation and actions.

## Pages

### Dashboard

An at-a-glance overview: Homebrew counts (formulae, casks, outdated, taps) and a **Package managers** card listing every detected manager with its version. Top-right shortcuts run Update / Upgrade-all / Clean up. Click a manager to jump into its package list.

### Installed

The list of installed packages for the selected provider. Search and (for Homebrew) filter by formula / cask / outdated / dependency. Click any row to open the **detail drawer** — description, versions, disk size, source/registry, homepage/repository, and for Homebrew also tap, install date, caveats, dependencies, and a dependency-graph button. Select multiple rows to uninstall them as one queued operation.

**Scan sizes** — click this button to measure on disk usage with a live progress bar. When done, each row shows its footprint, the total is displayed, and the list can sort by size (like a disk cleaner). Results are cached, so revisiting the page doesn't re-scan.

### Updates

Outdated packages for the selected provider, with installed → latest versions and an **Upgrade** button per row (plus **Upgrade all** where supported).

- For Homebrew, updates load automatically; a **greedy** toggle includes auto-updating casks.
- For other providers, updates are **on-demand**: click **Check for updates** to query each package's registry with a progress bar. This works even for managers with no native outdated command (bun, cargo, go). Results persist across navigation; unreachable packages are reported rather than silently treated as up to date.

### Discover

Search the catalog and install new packages. Homebrew and some managers support full search; others (e.g. pip, go) switch to an **install-by-name** form where you type the exact package name.

### Services

Homebrew services (databases, daemons) managed via `launchd` — start, stop, and restart background services, with a status dot per service.

### Taps

Manage Homebrew **taps** — third-party repositories that provide formulae and casks beyond the core. Add one in `owner/repo` form; remove with the trash icon. (Other managers don't use taps — they install from a single configured source, shown on the Managers page and in each package's detail.)

### Managers

Shows every package manager: installed ones with their version, scope, and configured source; missing ones with an **Install** button (via Homebrew). Update a manager in place where it supports self-update.

### Maintenance

Homebrew housekeeping: reclaim disk space (cleanup / prune), remove unused dependencies (autoremove), run diagnostics (`brew doctor`), and view the largest installed packages.

### Security

Free CVE scanning via [OSV.dev](https://osv.dev). Pick a provider with a supported ecosystem (npm/PyPI/crates.io/RubyGems/Go), click scan, and review any vulnerabilities with severity, fixed-in version, and a link. Homebrew has no OSV ecosystem and is not scannable here.

### Assistant

An optional AI helper. Configure a provider in **Settings**: choose a preset (OpenAI / Anthropic / DeepSeek / Zhipu GLM / Moonshot Kimi / xAI Grok / Google Gemini) or a custom OpenAI-compatible endpoint, set the base URL, model, and API key. The assistant can analyze disk usage, security findings, updates, dependencies, alternatives, or answer free-form questions, streaming its response. Your key is stored locally (`~/.config/brewbar/ai.json`, `0600`) and never sent to the browser.

### Brewfile

Back up, restore, and **diff** your Homebrew setup against a `Brewfile`: see what's installed but not declared (extra) and what's declared but not installed (missing), then sync.

### Settings

Language (English / 简体中文), theme (light / dark), default Brewfile path, the AI assistant configuration, and toggles such as dependents-check and greedy-by-default.

## Tips

- brewbar never runs anything you didn't confirm; when in doubt, read the command-preview dialog.
- Expensive operations (size, updates, CVE) are always **on demand** — nothing slow happens until you click.
- Everything is local: no account, no telemetry, no network access except the registries you explicitly scan and the AI endpoint you configure.