Bullpen CLI Quickstart¶

Bullpen CLI lets you authenticate, view portfolio balances, discover prediction markets, and trade from the terminal.

v0.1.117 is unreleased

This page describes the v0.1.117 release candidate. The latest published release is v0.1.116, which remains the version installed by normal install and upgrade commands until v0.1.117 is tagged and published.

System Requirements¶

Requirement	Details
Operating systems	macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2

Install¶

Bullpen CLI holds keys and signs trades. The native installer is the recommended first install; it downloads the latest published official release binary from one of Bullpen's two canonical provenance sources. Manual download from GitHub Releases is the other canonical provenance path for users who want to verify checksums themselves or pin a version. Homebrew and npm are supported installers, not additional canonical provenance sources. To inspect the installer before running it, compare SHA-256 checksums, or understand the Homebrew trust prompt, see Verifying Your Install.

If this page mentions an unreleased candidate, normal install and upgrade commands still install the latest published release until that candidate is tagged and published.

Native Installer (Recommended)¶

Run the native installer when you choose the direct Bullpen install path for this machine:

State change: This downloads and installs the Bullpen CLI binary.

curl -fsSL https://cli.bullpen.fi/install.sh | sh

Use the native installer for the simplest first install. It downloads the latest published Bullpen release binary directly from https://cli.bullpen.fi/install.sh and does not depend on Homebrew tap trust. To read the script before running it:

curl -fsSL https://cli.bullpen.fi/install.sh -o install.sh
less install.sh      # review it
sh install.sh

Windows 11 (WSL2)¶

Bullpen runs on Windows through Ubuntu on WSL2. On Windows 11 and recent Windows 10 builds, run this once in PowerShell:

wsl --install -d Ubuntu

On older Windows 10 builds, wsl --install -d Ubuntu may not be recognized; run wsl --update first, or follow Microsoft's manual WSL2 enablement steps, then retry. Open Ubuntu from the Start menu, then install Bullpen inside the Ubuntu terminal. Not copy-pasteable as one sequence: run the installer only when setting up WSL.

sudo apt update
sudo apt install -y curl ca-certificates
curl -fsSL https://cli.bullpen.fi/install.sh | sh
bullpen status
bullpen doctor auth

Not copy-pasteable as a setup sequence: run bullpen login only if bullpen status or bullpen doctor auth says login is required. Rerun bullpen status after login. Install skills only when you want AI-assistant integration.

bullpen skill install --dry-run

Live: This installs or updates local AI-assistant skill files inside the Ubuntu environment.

bullpen skill install

After bullpen skill install, restart your AI assistant (Claude Code, Codex CLI, etc.) so it picks up the skills.

Run all Bullpen commands — including bullpen skill install and shell completion — inside the Ubuntu terminal, not Windows PowerShell or Command Prompt.

WSL caveats:

The browser lives on the Windows side, so device-login URLs open in your Windows browser. If diagnostics require login and auto-open fails, run bullpen login --no-browser and paste the displayed verification URL into a Windows browser manually.
WSL clock skew can break auth and JWT validation. If logins fail with auth or time errors, run sudo hwclock -s inside Ubuntu, or run wsl --shutdown from PowerShell to restart WSL and resync the clock.

npm¶

npm install -g @bullpenfi/cli

Homebrew (macOS / Linux)¶

brew install BullpenFi/tap/bullpen

If Homebrew refuses to load the Bullpen formula from an untrusted tap, run:

brew trust --formula bullpenfi/tap/bullpen
brew install BullpenFi/tap/bullpen
brew link --overwrite bullpen

Homebrew requires explicit trust for some third-party taps. Trust the formula only when the tap is BullpenFi/tap and you are comfortable installing the Bullpen-maintained formula. To trust the full Bullpen tap instead of just the formula, run brew trust --tap bullpenfi/tap. For first installs, the native installer avoids this Homebrew trust step.

Manual Download¶

Download the latest published binary from Releases. Before running it, compare the SHA-256 of the downloaded file against the checksum published on the release page:

shasum -a 256 ./bullpen

The release page lists SHA-256 checksums for each artifact. See Verifying Your Install for the full checksum and provenance walkthrough.

If bullpen is not found after install, ensure the install location is on your PATH.

Getting Started¶

Recommended setup order: install, check bullpen status, run bullpen doctor auth, log in only when diagnostics require it, rerun bullpen status, preview the first action, confirm only after review, then install skills and restart your AI assistant.

Reserve bullpen doctor auth --refresh --output json and bullpen fix --refresh for stale or expired sessions, support requests, or cases where diagnostics explicitly ask for refreshed evidence.

Check local login and cached session state:
```
bullpen status
```
Inspect auth diagnostics:
```
bullpen doctor auth
```
Log in only when status or auth diagnostics report that login is required:
```
bullpen login
```
A code and URL are displayed. Open the URL in your browser.
Enter the code and complete login in the browser.
The CLI automatically picks up your session — no copy-pasting required.
Re-check local login and cached session state:
```
bullpen status
```
Check your balances:
```
bullpen portfolio balances
```

First Successful Prediction Trade¶

Use the simple journey commands first. They keep the terminal output focused on what you can do next.

Not copy-pasteable as one sequence: start with passive auth checks, run login only when diagnostics require it, then continue.

bullpen status
bullpen doctor auth

Run bullpen login only if diagnostics direct you to log in:

State change: This starts device login and stores the resulting local session after browser approval.

bullpen login

After login completes, re-check local login and cached session state:

bullpen status

Refresh active readiness only if the status or auth output asks for it:

State change: This refreshes account readiness diagnostics and may update local diagnostic state.

bullpen fix --refresh

Find a market and choose a slug:

bullpen polymarket search "bitcoin" --type market --limit 5

Preview a trade with the returned slug. Preview mode does not sign or submit anything.

bullpen trade buy <MARKET_SLUG_FROM_SEARCH> No 5 --max-price 0.01 --preview --output json

Live: trade mutation. Submit only after the preview matches your intent.

bullpen trade buy <MARKET_SLUG_FROM_SEARCH> No 5 --max-price 0.01 --yes

Inspect the resulting position.

bullpen polymarket positions --source polymarket --output json

Preview a complete close, then submit it with a price floor.

bullpen trade sell <MARKET_SLUG_FROM_SEARCH> No --max --min-price 0.001 --preview --output json

Live: trade mutation. Submit only after the sell preview matches your intent.

bullpen trade sell <MARKET_SLUG_FROM_SEARCH> No --max --min-price 0.001 --yes

Verify open orders are gone and check whether any active position or dust remains.

bullpen polymarket orders --output json
bullpen polymarket positions --source polymarket --output json

Polymarket market buys spend pUSD collateral and require at least $1 of executable spend. They may still reject if the live order would produce too few shares for that market's current minimum. Sells, limit buys, and limit sells use share amounts and must meet the market's current minimum order size. Market sells round down to two-decimal share precision and may leave a sub-0.01 unsellable dust balance.

Choose a --min-price that matches the live market and your acceptable loss. Do not copy the illustrative 0.001 floor without reviewing the preview. If the close cannot complete or the position remains active, run bullpen support bundle --output json instead of repeatedly submitting orders.

If bullpen fix --refresh says support should review the account, run:

bullpen support bundle --output json

The support bundle command writes a passive redacted JSON artifact and prints its path. This file is on this machine and has not been uploaded; attach the JSON file to your support ticket.

TUI Mode: Run bullpen with no arguments to launch the interactive terminal UI. See the TUI Guide for layout, key bindings, slash commands, and exit shortcuts.

AI Agent Mode: Install skills with bullpen skill install, restart Claude Code or Codex CLI, then trade through natural language.

For a deeper explanation of auth state, credential storage, and support capture, see Authentication.

If Something Looks Wrong¶

Start with passive checks:

bullpen status
bullpen doctor auth

Run bullpen fix --refresh only when status, auth diagnostics, or the failed command asks for refreshed readiness evidence. It checks login, wallet readiness, balances, and common recovery states, then prints one next action. Run bullpen support bundle --output json only when that output or Bullpen Support asks for a redacted artifact. The file remains on this machine until you attach it to a ticket. Avoid switching wallets or repeatedly retrying live trades unless the CLI or support gives that exact next step.

Advanced wallet details¶

Bullpen supports older Safe / Proxy accounts and newer Deposit Wallet accounts. Normal users do not need to choose between them: the CLI uses the wallet route reported for your Bullpen account and fails closed when that route is inconsistent. Use the advanced wallet guides only when bullpen fix --refresh, bullpen support bundle --output json, or Bullpen support asks for them.

Expected output (example):

Total USD (All): 1234.56

[Solana] Address: ...  Chain: Solana (0)
Total USD: 345.67
Symbol          Balance        Value USD
SOL            1.2345            123.45
USDC          10.0000            10.00

[Hyperliquid Spot] Address: ...  Chain: HyperCore Spot (6)
Total USD: 456.78
Symbol          Balance        Value USD
USDC          100.0000          100.00

[Polymarket] Address: ...  Chain: Polygon (10)
Total USD: 432.11
Symbol          Balance        Value USD
pUSD           432.1100         432.11

If you see USDC.e instead of pUSD, start with the preview command: bullpen polymarket wrap <amount> --preview --output json. It does not submit the wrap transaction.

Live: Run bullpen polymarket wrap <amount> --yes only when the preview plan looks right; it submits the wrap transaction. If native Polygon USDC is visible on-chain, start with bullpen recover funds --dry-run --output json; the plan will show whether the CLI can convert it toward the Polymarket pUSD path or whether support needs to review diagnostics. If native Polygon USDC is visible on-chain but the CLI reports zero, upgrade and rerun the dry-run before opening a support ticket.

AI Agent Skills¶

Install skills so Claude Code or Codex CLI can trade on your behalf. Preview the write first when you want to inspect target paths:

Preview the local file changes:

bullpen skill install --dry-run --output json

Live: After reviewing the matching dry-run above, install or update the local AI-assistant skill files:

bullpen skill install

Restart Claude Code or Codex CLI after installing.

What Balances Are Included¶

The CLI fetches balances through Bullpen for: - Solana - Hyperliquid (HyperCore Spot + Perps) - Polymarket (Polygon)

Configuration¶

Config lives at ~/.bullpen/config.toml (or $BULLPEN_HOME/config.toml). To generate a default config:

State change: This initializes a missing or intentional local config profile.

bullpen config init

To force a different environment:

bullpen --env staging portfolio balances

For precedence across --config, BULLPEN_CONFIG, BULLPEN_HOME, --env, read-only mode, non-interactive mode, and telemetry controls, see Configuration.

Update notifications: The CLI automatically checks for updates in the background and prints a notice to stderr when a newer version is available. This check is non-blocking and does not slow down commands. To disable, add check_for_updates = false to your config.toml.

Upgrade experience: Normal upgrades preserve your local session. If an upgrade reports that local sign-in data cannot be read, run bullpen status --output json and bullpen doctor auth --output json first. Keep that output if you need support. Use bullpen doctor auth --refresh --output json only when diagnostics request fresh evidence. Run bullpen login only when diagnostics require a fresh session. Use bullpen logout --force only as a last-resort local reset.

What's New¶

For the most recent public release notes, see the Changelog, the Roadmap, and GitHub Releases. Run bullpen --version to see your installed version, and bullpen upgrade to update. Homebrew and npm installs delegate to the package manager before checking GitHub releases, so shared-IP GitHub API limits should not block those upgrade paths. Homebrew recovery: brew update, brew upgrade bullpen, then brew link --overwrite bullpen; if Homebrew asks whether the Bullpen formula is trusted, run brew trust --formula bullpenfi/tap/bullpen and retry. npm recovery: npm install -g @bullpenfi/cli@latest.

Diagnostics¶

Create a support bundle when diagnostics ask for one:

bullpen support bundle --output json

Uninstall¶

Step 1: Remove AI skills (optional)¶

If you installed AI skills, remove them first.

State change: This removes installed Bullpen skill files.

bullpen skill uninstall --yes

Step 2: Remove the binary¶

HomebrewnpmShell Script / Manual

brew uninstall bullpen
brew untap bullpenfi/tap  # optional: remove the tap

npm uninstall -g @bullpenfi/cli

rm "$(which bullpen)"
# Also remove from PATH in ~/.zshrc or ~/.bashrc if added by the installer:
# Delete the line: export PATH="$HOME/.bullpen/bin:$PATH"

Step 3: Clean up local data (permanent uninstall only)¶

State change: For normal credential clearing, run:

bullpen logout

State change: If local auth files are unreadable or support asks for a full local reset, use:

bullpen logout --force

These commands clear credentials for the active profile without deleting your entire Bullpen config directory.

Remove ~/.bullpen only when you are permanently uninstalling Bullpen from this machine and no longer need local config, logs, credentials, or keys.

State change: This permanently removes local Bullpen data for the default profile.

rm -rf ~/.bullpen

Warning

This permanently deletes your stored credentials, Turnkey keys, config, and local logs for the default profile. You'll need to log in again if you reinstall.

Next Steps¶

Prediction (Polymarket) — discover, search, and analyze markets (event details, price history, trades, holders, leaderboard, smart money, social & community)
Trading — buy, sell, redeem shares, and place limit orders
Authentication — understand login, session recovery, and support-safe auth diagnostics
Configuration — configure environments, isolated homes, read-only mode, and automation defaults
Output and Errors — understand --output json, exit codes, typed errors, and support capture
Orders and Watchlist — manage orders and watchlist
TUI Guide — use the full-screen terminal UI, key bindings, slash commands, and escape routes
Perps (Hyperliquid) — trade perpetual futures with leverage, manage positions, and manage orders
Perps First Trade — start with read-only account checks, preview a Perps trade, and submit only after review
Spot (Hyperliquid) — discover spot pairs, inspect spot liquidity, preview IOC spot orders, and manage spot cancels/TWAPs
Onchain (Solana) — use experimental Solana balances, token reads, swaps, limit orders, DCA, withdraw, and deposit guidance
Onchain Solana First Trade — fund your Bullpen-managed Solana wallet, preview a Jupiter buy, submit explicitly, and reconcile balances afterward
Advanced Wallet Model — understand Safe, Proxy, and Deposit Wallet routing. For trade, wallet, or missing-funds errors, start with bullpen status --output json and bullpen doctor wallet --output json. Run a recovery command only when the diagnostics recommend it.
Command Reference — complete per-command reference for all commands
LLM Bundle — single-file concatenation of public docs for LLM ingestion

Goal	Command
Check CLI and account status	`bullpen status`
View profit and loss	`bullpen portfolio pnl`
View points	`bullpen points`
View rewards	`bullpen rewards`
View notifications	`bullpen notifications`
Browse active Prediction markets	`bullpen polymarket markets --active --sort volume`
Read large-trader activity	`bullpen polymarket feed trades --min-pnl 10000`