Skip to content

Bullpen CLI Quickstart

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

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 official release binary from the canonical source. Manual download is for users who want to verify checksums themselves or pin a version. To inspect the installer before running it, compare SHA-256 checksums, or understand the Homebrew trust prompt, see Verifying Your Install.

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

Use the native installer for the simplest first install. It downloads the latest 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:

sudo apt update
sudo apt install -y curl ca-certificates
curl -fsSL https://cli.bullpen.fi/install.sh | sh
bullpen login
bullpen status
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 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 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, log in, check status, install skills, then restart your AI assistant.

After bullpen status, run bullpen fix --refresh if the CLI says action is needed.

  1. Log in (device auth): 
    bullpen login
  2. A code and URL are displayed. Open the URL in your browser.
  3. Enter the code and complete login in the browser.
  4. The CLI automatically picks up your session — no copy-pasting required.
  5. Check login and trading readiness: 
    bullpen status
  6. If status says action is needed, let Bullpen show one safe next step: 
    bullpen fix --refresh
  7. Check your balances: 
    bullpen portfolio balances

First Successful Prediction Trade

Use the simple journey commands first. They run the same underlying Polymarket trade and recovery logic, but keep the terminal output focused on what you can do next.

# Run active readiness checks before trading.
bullpen fix --refresh

# Find a market.
bullpen polymarket search "bitcoin" --type market --limit 5

# Preview a trade. Preview mode does not sign or submit anything.
bullpen trade buy will-ronaldo-cry-at-the-world-cup-20260604013616610 No 5 --preview --output json

# Submit only after the preview matches your intent.
bullpen trade buy will-ronaldo-cry-at-the-world-cup-20260604013616610 No 5 --max-price 0.01 --yes

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

bullpen support

The command writes a redacted diagnostic artifact and prints a short copy/paste summary for Bullpen support.

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 login state, credential storage, and support capture, see Authentication.

If Something Looks Wrong

Start with the high-level commands:

bullpen fix --refresh
bullpen support

bullpen fix --refresh checks login, wallet readiness, balances, and common recovery states, then prints one next action. bullpen support creates a support-safe artifact when the issue needs Bullpen review. Avoid switching wallets or retrying live trades repeatedly 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, 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, preview the conversion first with bullpen polymarket wrap <amount> --preview --output json, then run bullpen polymarket wrap <amount> --yes when the plan looks right. Use the same preview flow for Polygon native USDC. If native USDC is visible on-chain but the CLI reports zero, upgrade and rerun the preview before opening a support ticket.

AI Agent Skills

Install skills so Claude Code or Codex CLI can trade on your behalf: 

bullpen skill install
# Restart Claude Code / Codex CLI after installing

What Balances Are Included

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

Configuration

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

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: Credential encryption uses a stable build-time key, so normal upgrades preserve your session. If an upgrade reports local credential or salt corruption, run bullpen doctor auth --output json first and preserve the output if you need support to inspect copied-home state. Restore the matching salt first only if you need to keep the old local session. Otherwise run bullpen login; it moves unreadable local auth files aside and starts a fresh session. Use bullpen logout --force && bullpen login 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.

Logging

Set RUST_LOG to enable file logging for non-passive commands: 

RUST_LOG=info bullpen doctor auth

Uninstall

Step 1: Remove AI skills (optional)

If you installed AI skills, remove them first:

bullpen skill uninstall --yes

Step 2: Remove the binary

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 (optional)

Remove configuration, credentials, and keys:

rm -rf ~/.bullpen

Warning

This deletes your stored credentials, Turnkey keys, and config. You'll need to log in again if you reinstall.

If you want to keep your config but clear credentials:

rm ~/.bullpen/credentials.json.enc
rm -rf ~/.bullpen/keys

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
  • Migrate Safe to Deposit Wallet — support-directed pUSD migration path only; for trade, wallet, or missing-funds errors, start with bullpen fix --refresh, bullpen recover polymarket, or bullpen support
  • Command Reference — complete per-command reference for all commands
  • LLM Bundle — single-file concatenation of public docs for LLM ingestion

Other useful commands: 

bullpen status                                                 # CLI + account status
bullpen portfolio pnl                                          # view profit & loss
bullpen points                                                 # view your points
bullpen rewards                                                # view and claim rewards
bullpen notifications                                          # view notifications
bullpen tracker add <polymarket_addr>                         # track a Polymarket wallet
bullpen polymarket price <slug>                     # real-time bid/ask/mid
bullpen polymarket market <slug>                    # detailed market info
bullpen polymarket markets --active --sort volume   # browse markets
bullpen deposit                                     # deposit funds (opens web app)
bullpen polymarket bridge --help                    # support-provided bridge status guidance
bullpen polymarket comments <slug>                  # view market comments
bullpen polymarket feed trades --min-pnl 10000      # filtered trade feed