Bullpen CLI Walkthrough¶
Use this walkthrough to get from a fresh Bullpen CLI install to a verified trading-ready account, market discovery, previewed orders, portfolio checks, and recovery diagnostics. The commands work on supported macOS, Linux, and Windows WSL2 setups unless a platform-specific note says otherwise.
Recommended path:
- Install the CLI and verify the binary.
- Check status and auth diagnostics; log in only when diagnostics require it.
- Discover markets, inspect prices, and preview before trading.
- Monitor positions, orders, and account diagnostics.
- Use recovery commands when wallet routing or funds state is unclear.
Need the shortest path first? Start with the Quickstart. For install integrity, see Verifying Your Install. For auth and copied-profile issues, see Authentication. For order workflows, see Prediction Trading. For wallet-route or funds recovery, see Wallet Routing And Funds Recovery.
1. Install¶
This is a non-runnable sequence: run the installer only after you choose the native install path for this machine.
Prefer the native installer for fresh machines. It downloads the latest
published official release binary from the canonical source
(https://cli.bullpen.fi/install.sh). If you use Homebrew and it refuses the
Bullpen tap as untrusted, that prompt is Homebrew confirming you intend to
install from the BullpenFi tap; run brew trust --formula bullpenfi/tap/bullpen
before retrying brew install BullpenFi/tap/bullpen. To inspect the installer
before running it or compare published SHA-256 checksums, see
Verifying Your Install.
On Windows, follow the WSL2 path in the Quickstart or Overview first, then continue from step 2 below inside your Ubuntu terminal.
Verify:
2. First-Time Setup¶
Start with passive status and auth diagnostics. Run login only when either diagnostic says it is required.
If status reports that the local profile is missing, initialize it, then rerun the passive checks:
State change: config init creates the missing local profile.
If either diagnostic says login is required, run bullpen login. A code and
URL are displayed. Open the URL in your browser, enter the code, and login
completes automatically.
Re-check local login and cached session state:
State change: This refreshes account readiness diagnostics and may update local diagnostic state. Run it only when status or auth diagnostics says refreshed readiness evidence is needed before moving money.
Before confirming any first money-moving action, run its preview and review the plan. Confirm only after the preview matches your intent.
Bullpen CLI v<latest-published-version> (Alpha)
Environment: production
Update: up to date
Account
Status: Logged in
Session: Ready
Readiness
Trading: Ready
Next step: Run `bullpen polymarket discover --limit 10`.
Use bullpen setup only after the diagnostic sequence above when you want the
guided account-readiness flow. It initializes config if needed, verifies login
state, checks Polymarket readiness, and prints the next safe step; it does not
replace the status -> doctor auth -> conditional login sequence.
3. Install AI Agent Skills (Optional)¶
Install skills so Claude Code or Codex CLI can trade on your behalf through natural language. Preview the install target first:
Live: Install or update local AI-assistant skill files only when you want assistant integration on this machine.
Installed 38 skill files to 1 location(s):
[Claude Code (personal)] /Users/you/.claude/skills/bullpen-cli
After installing, restart Claude Code or Codex CLI. Then just ask:
- "Find an active prediction market, preview a guarded buy, then wait for my confirmation."
- "Show me trending crypto prediction markets"
- "What are my open positions?"
4. Check Your Account¶
Bullpen CLI v<latest-published-version> (Alpha)
Environment: production
Update: up to date
Account
Status: Logged in
Session: Ready
Readiness
Trading: Ready
Next step: Run `bullpen polymarket discover --limit 10`.
Polymarket
Status: UP
╭──────────────────────────────────╮
│ Total Portfolio Value +$337.30 │
│ $372.71 │
├──────────────────────────────────┤
│ Solana -$15.66 │
│ $19.75 │
├──────────────────────────────────┤
│ Hyperliquid $0.00 │
│ $0.00 │
├──────────────────────────────────┤
│ Polymarket +$352.96 │
│ $352.96 │
╰──────────────────────────────────╯
5. Discover Markets¶
Browse trending markets:
Market Odds Vol 24h Liquidity Ends
-----------------------------------------------------------------------------------------------------
Example active market Yes 14¢ / No 86¢ $9.6M $664.1K Active
... and 62 more markets
Example high-liquidity market Yes 28¢ / No 72¢ $7.6M $62.4K Active
... and 27 more markets
Example macro market Yes 63¢ / No 37¢ $7.0M $6.0M Active
... and 3 more markets
Example sports market Yes 42¢ / No 58¢ $3.6M $143.3K Active
... and 30 more markets
Example politics market Yes 51¢ / No 49¢ $5.0M $143.4K Active
... and 54 more markets
Filter by category:
Market Odds Vol 24h Liquidity Ends
-----------------------------------------------------------------------------------------------------
Example crypto market Yes 48¢ / No 52¢ $846.8K $478.2K Active
... and 8 more markets
Example weekly crypto market Yes 35¢ / No 65¢ $807.0K $128.0K Active
... and 20 more markets
Example asset-price market Yes 54¢ / No 46¢ $212.9K $403.3K Active
... and 8 more markets
Search for a specific topic:
Markets (10 results)
Market Odds Vol 24h Liquidity
-----------------------------------------------------------------------------------------
Example bitcoin market Yes 58¢ / No 42¢ $4.5M $4.9M
Example bitcoin range market Yes 31¢ / No 69¢ $4.5M $4.9M
Example bitcoin weekly market Yes 47¢ / No 53¢ $4.5M $4.9M
Example bitcoin daily market Yes 52¢ / No 48¢ $4.5M $4.9M
Example bitcoin milestone market Yes 24¢ / No 76¢ $3.1M $7.0M
Example bitcoin downside market Yes 18¢ / No 82¢ $3.1M $7.0M
...
6. Research a Market¶
Pick a slug from bullpen polymarket discover --limit 5 or
bullpen polymarket search <query>, then store it for the rest of the
walkthrough:
Drill in:
bullpen polymarket price "$ACTIVE_MARKET_SLUG"
bullpen polymarket trades "$ACTIVE_MARKET_SLUG"
bullpen polymarket holders "$ACTIVE_MARKET_SLUG"
7. Place a Trade¶
Preview first (no execution):
Order Preview
───────────────────────────────────
Action: Buy No
Market: Example active market
Amount: $5.00
Price: 1.7¢
Est. Shares: 294.11
Potential: $294.11
Trading Fee: $0.01
Network Fee: ~$0.01
Total Cost: $5.02
Spread: 99.8¢
───────────────────────────────────
Live: submit the market buy only after the preview above matches your intended market, outcome, amount, and max price:
Preview-only safety check for the limit order; this does not write or submit:
bullpen polymarket limit-buy "$ACTIVE_MARKET_SLUG" Yes --price 0.01 --shares 100 --preview --output json
Live: submit the limit buy only after reviewing the preview above:
8. Manage Positions & Orders¶
View your positions:
Portfolio Value: $89.80 | Cash: $0.00 | Unrealized P&L: +$4.37
Market Outcome Shares Avg Price Value P&L P&L %
------------------------------------------------------------------------------------------------------
Example active market Yes 36.0 14¢ 14¢ 5.22 +$0.17 3.5%
Example high-liquidity market Yes 33.0 15¢ 16¢ 5.11 +$0.16 3.3%
Example macro market Yes 28.9 23¢ 22¢ 6.21 -$0.56 -8.2%
Example sports market Yes 18.8 36¢ 36¢ 6.70 -$0.04 -0.6%
Example crypto market No 13.5 75¢ 99¢ 13.47 +$3.32 32.7%
Example downside market No 13.5 74¢ 99¢ 13.41 +$3.42 34.2%
Example index market Yes 8.3 60¢ 55¢ 4.58 -$0.41 -8.3%
Example entertainment market Yes 5.0 48¢ 48¢ 2.42 +$0.02 1.0%
...
View open orders:
Market ID Outcome Side Price Size Filled Type
--------------------------------------------------------------------------------------------------
Example active market <ORDER_ID> Yes BUY 8¢ 5.00 0.00 GTC
...
View trade history:
Activity (showing 5)
Time Type Market Side Amount USDC
──────────────────────────────────────────────────────────────────────────────────────
2026-07-23T18:34:09 TRADE Example active market BUY 10.0 $1.50
2026-07-23T17:14:07 TRADE Example high-liquidity market BUY 13.0 $1.95
2026-07-23T16:31:03 TRADE Example macro market BUY 10.0 $1.50
2026-07-23T14:35:23 TRADE Example sports market BUY 16.6 $2.32
2026-07-23T14:35:23 TRADE Example crypto market BUY 0.6 $0.14
9. Leaderboard & Trader Intelligence¶
View the weekly leaderboard:
# Username Address Volume P&L Win Rate Trades
-----------------------------------------------------------------------------------------------
1 gmanas <TRADER_ADDRESS> $22.9M +$1.7M - -
2 lfc123 <TRADER_ADDRESS> $4.8M +$749.2K - -
3 joosangyoo <TRADER_ADDRESS> $8.4M +$540.3K - -
4 example-wallet-1 <TRADER_ADDRESS> $31.5M +$459.4K - -
5 gopatriots <TRADER_ADDRESS> $4.5M +$415.5K - -
6 predictorxyz <TRADER_ADDRESS> $540.3K +$410.4K - -
7 example-wallet-2 <TRADER_ADDRESS> $1.7M +$392.0K - -
8 kch123 <TRADER_ADDRESS> $1.6M +$389.1K - -
9 GamblingIsAllYouNeed <TRADER_ADDRESS> $11.6M +$354.8K - -
10 example-wallet-3 <TRADER_ADDRESS> $1.7M +$354.2K - -
View the daily leaderboard:
# Username Address Volume P&L Win Rate Trades
-----------------------------------------------------------------------------------------------
1 weflyhigh <TRADER_ADDRESS> $430.4K +$400.4K - -
2 Countryside <TRADER_ADDRESS> $610.9K +$346.1K - -
3 kch123 <TRADER_ADDRESS> $352.4K +$167.6K - -
4 joosangyoo <TRADER_ADDRESS> $772.8K +$150.0K - -
5 example-wallet-4 <TRADER_ADDRESS> $135.6K +$127.8K - -
10. Trade Feed¶
Watch the live trade feed filtered to large trades:
Filtered Trades (10 total, page 1)
Market Side Price Size Trader PnL Tracked
--------------------------------------------------------------------------------
Example sports market SELL 1¢ $591 -$314 -
Example macro market BUY 4¢ $2.6K $0 -
Example soccer market BUY 80¢ $798 $760 -
Example asset-price market SELL 7¢ $643 -$109 -
Example match market BUY 68¢ $2.0K $4.3M -
Example bitcoin market BUY 59¢ $508 -$6.2K -
Example social market BUY 0¢ $8.1K -$65 -
11. Watchlist¶
Add one item to your watchlist.
State change: Add a Prediction market:
State change: Add an Onchain (Solana) token:
State change: Add a Perps market:
View your watchlist:
12. JSON Output & Scripting¶
Most data and automation commands support --output json for programmatic use.
Raw output commands such as bullpen completion, interactive commands such as
bullpen shell, and unsupported streaming previews reject JSON mode. Check the
per-command reference page before wiring a command into automation.
This is a non-runnable sequence: run these examples only after choosing a live
market slug and deciding which JSON projection you need.
bullpen polymarket positions --output json | jq '.positions[:3] | .[] | {market: .title, outcome, pnl, pnl_pct}'
13. Interactive Shell¶
Launch the REPL — runs commands without the bullpen prefix:
Inside the shell:
bullpen> polymarket discover --limit 5
bullpen> polymarket price <MARKET_SLUG_FROM_DISCOVER>
bullpen> portfolio overview
bullpen> exit
For the full-screen terminal UI, run bullpen with no arguments. See the TUI Guide for layout, key bindings, slash commands, and exit shortcuts.
14. Upgrade¶
This is a non-runnable sequence: run upgrade only when you intend to update the local binary to a published release.
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 only when
diagnostics report that login is required; it moves unreadable local auth files
aside and starts a fresh session. Use bullpen logout --force only as a
last-resort local reset after preserving diagnostic/support evidence, then run
bullpen login only if diagnostics still require login.
Most upgrades preserve the session as long as local credentials and refresh
tokens remain valid.
Release Notes¶
For the most recent release notes, see the CHANGELOG. 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. 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.
Demo Tips¶
--previewon trading commands shows what would happen without executing — great for demos.--output json | jq .on JSON-capable commands to show structured data.bullpen shellfeels like a native trading terminal — impressive for live demos.bullpenopens the full-screen TUI when you want scrollback and autocomplete; see the TUI Guide.- Tab completion:
bullpen completion zsh >> ~/.zshrc && source ~/.zshrc. - For demos, pick any high-liquidity active market from
bullpen polymarket discover --limit 5; avoid hard-coding event-dated slugs in docs.