CLI Reference¶
Complete flag-by-flag reference for the Bullpen CLI.
Global Flags¶
These flags work with any command.
| Flag | Type | Description |
|---|---|---|
--output |
table, json |
Output format (default: table) |
--env |
staging, production |
Override environment |
--config |
path | Custom config file path |
--trade-server-url |
string | Override trade server URL |
Interactive TUI Mode¶
Running bullpen with no subcommand launches an interactive terminal UI (TUI) powered by ratatui. The TUI provides a full-screen interface for browsing markets, managing positions, and executing trades without needing to remember individual commands.
Global flags (--output, --env, --config, --trade-server-url) are accepted and passed through to the TUI session.
Authentication¶
bullpen auth login¶
Authenticate with Bullpen via email, Google, X, or browser (experimental).
The default login method is Email OTP. Browser login requires enabling the device_login experimental feature (see Experimental Features).
| Flag | Type | Description |
|---|---|---|
--method |
email, google, x, browser |
Login method (default: interactive prompt, email first) |
--identifier |
string | Email or username (email method) |
--otp |
string | One-time password (email method) |
--oauth-login-response |
string | OAuth response string |
--oauth-login-response-file |
path | Read OAuth response from file |
--oauth-login-response-stdin |
flag | Read OAuth response from stdin |
--oauth-login-response-clipboard |
flag | Read OAuth response from clipboard |
--webapp-url |
string | Override web app URL for browser login |
--non-interactive |
flag | Non-interactive mode |
bullpen auth request-otp¶
Request a one-time password for email authentication.
| Flag | Type | Description |
|---|---|---|
--identifier |
string | Email or username |
--non-interactive |
flag | Non-interactive mode |
bullpen auth logout¶
Log out and clear stored credentials.
No flags.
bullpen auth status¶
Check authentication status.
No flags.
Configuration¶
bullpen config init¶
Initialize or update configuration.
| Flag | Type | Description |
|---|---|---|
--env |
staging, production |
Environment |
--usergate-url |
string | Custom usergate URL |
--output-format |
table, json |
Default output format |
--credential-store |
auto, keyring, file, ephemeral |
Credential storage |
--trade-server-url |
string | Trade server URL |
Credential Store Behavior:
- file (default): store credentials in ~/.bullpen/credentials.json
- auto: uses OS keychain when available, falls back to local file
- keyring: always use OS keychain (fails if unavailable)
- ephemeral: store in memory only for the current process
Auto-init on Login: Running bullpen auth login without a config file creates a default config at ~/.bullpen/config.toml (production).
Example config.toml:
env = "production"
usergate_url = "https://usergate.bullpen.fi"
output_format = "table"
credential_store = "file"
check_for_updates = true
trade_server_url = "https://trade.bullpen.fi"
[experimental]
device_login = false
Update Checking: The CLI automatically checks for updates on startup and shows a notice on stderr if a newer version is available. To disable:
Portfolio¶
bullpen portfolio balances¶
View portfolio balances across all chains.
No subcommand-specific flags.
bullpen portfolio pnl¶
View portfolio profit and loss summary. Requires authentication.
No subcommand-specific flags.
Prediction Markets¶
bullpen prediction polymarket discover [LENS]¶
Discover prediction markets through different lenses.
bullpen prediction polymarket discover
bullpen prediction polymarket discover sports
bullpen prediction polymarket discover crypto --min-volume 100000
bullpen prediction polymarket discover walletscope --address 0x1234...
Available Lenses:
- all (default) - All markets
- sports - Sports markets
- crypto - Crypto markets
- walletscope - Markets based on wallet activity
- eventscope - Event-based markets
- pulse - Trending and timely markets
- traders - Markets popular with top traders
- flow - Market flow analysis
| Flag | Type | Default | Description |
|---|---|---|---|
--search |
string | Search markets by title | |
--category |
string | Filter by category/tag | |
--min-liquidity |
number | Minimum liquidity | |
--min-volume |
number | Minimum volume | |
--min-odds |
number | Minimum odds percentage (e.g., 50 for 50%) | |
--status |
string | active |
Market status: active, closed |
--sort |
string | Sort: volume, volume24h, liquidity, newest, ending-soon | |
--limit |
number | 20 |
Number of results |
--offset |
number | Pagination offset | |
--address |
string | Wallet address (required for walletscope and flow lenses) |
bullpen prediction polymarket positions¶
View active or closed positions.
bullpen prediction polymarket positions --address 0x1234...
bullpen prediction polymarket positions --address 0x1234... --closed
bullpen prediction polymarket positions --address 0x1234... --redeemable
| Flag | Type | Description |
|---|---|---|
--address |
string | Required. Wallet address |
--closed |
flag | Show closed positions instead of active |
--redeemable |
flag | Show only redeemable positions |
bullpen prediction polymarket buy¶
Buy shares in a prediction market.
bullpen prediction polymarket buy will-trump-win Yes 100
bullpen prediction polymarket buy btc-above-100k No 50 --yes
| Arg/Flag | Type | Description |
|---|---|---|
MARKET_SLUG |
positional | Required. Market slug (e.g., "will-trump-win") |
OUTCOME |
positional | Required. Outcome name (e.g., "Yes" or "No") |
AMOUNT_USD |
positional | Required. Amount in USD |
--trade-server-url |
string | Required. Trade server URL (env: BULLPEN_TRADE_SERVER_URL) |
--access-token |
string | Required. Access token (env: BULLPEN_ACCESS_TOKEN) |
--address |
string | Required. Wallet address |
--yes |
flag | Skip confirmation |
Exit Codes:
- 0 - Success
- 3 - Trade failed
bullpen prediction polymarket sell¶
Sell shares in a prediction market.
bullpen prediction polymarket sell will-trump-win Yes 50
bullpen prediction polymarket sell btc-above-100k No 100 --yes
| Arg/Flag | Type | Description |
|---|---|---|
MARKET_SLUG |
positional | Required. Market slug |
OUTCOME |
positional | Required. Outcome name |
SHARES |
positional | Required. Number of shares to sell |
--trade-server-url |
string | Required. Trade server URL (env: BULLPEN_TRADE_SERVER_URL) |
--access-token |
string | Required. Access token (env: BULLPEN_ACCESS_TOKEN) |
--address |
string | Required. Wallet address |
--yes |
flag | Skip confirmation |
Exit Codes:
- 0 - Success
- 3 - Trade failed
bullpen prediction polymarket redeem¶
Redeem winnings from resolved markets.
| Flag | Type | Description |
|---|---|---|
--trade-server-url |
string | Required. Trade server URL (env: BULLPEN_TRADE_SERVER_URL) |
--access-token |
string | Required. Access token (env: BULLPEN_ACCESS_TOKEN) |
--address |
string | Required. Wallet address |
--condition-ids |
string | Required. Comma-separated condition IDs |
--yes |
flag | Skip confirmation prompt |
Exit Codes:
- 0 - Success
- 3 - Redeem failed
bullpen prediction polymarket orders¶
View or manage orders.
bullpen prediction polymarket orders --address 0x1234...
bullpen prediction polymarket orders --address 0x1234... --history
bullpen prediction polymarket orders --address 0x1234... --cancel abc123
| Flag | Type | Description |
|---|---|---|
--address |
string | Required. Wallet address |
--history |
flag | Show past trade history |
--cancel |
string | Cancel order by ID |
--trade-server-url |
string | Trade server URL (needed for cancel, env: BULLPEN_TRADE_SERVER_URL) |
--access-token |
string | Access token (needed for cancel, env: BULLPEN_ACCESS_TOKEN) |
bullpen prediction polymarket watchlist¶
Manage your market watchlist.
bullpen prediction polymarket watchlist
bullpen prediction polymarket watchlist --add will-trump-win
bullpen prediction polymarket watchlist --remove btc-above-100k
| Flag | Type | Description |
|---|---|---|
--add |
string | Add market by slug |
--remove |
string | Remove market by slug |
No flags = list watchlist.
bullpen prediction polymarket search¶
Search prediction markets and trader profiles.
bullpen prediction polymarket search "bitcoin"
bullpen prediction polymarket search "trump" --type market --status active
bullpen prediction polymarket search "vitalik" --type user --limit 5
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
QUERY |
positional | Required. Search query | |
--type |
all, market, user |
all |
Filter by result type |
--limit |
number | Number of results per type | |
--status |
active, closed |
Filter by market status |
bullpen prediction polymarket event¶
View detailed information about a specific prediction market event.
| Arg | Type | Description |
|---|---|---|
SLUG |
positional | Required. Event slug |
bullpen prediction polymarket price-history¶
Show price history for a market outcome.
bullpen prediction polymarket price-history will-bitcoin-hit-100k --outcome Yes
bullpen prediction polymarket price-history will-bitcoin-hit-100k --outcome No --interval 1w
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
SLUG |
positional | Required. Market slug | |
--outcome |
string | Required. Outcome name (e.g., "Yes" or "No") | |
--interval |
1h, 6h, 1d, 1w |
1d |
Time interval |
bullpen prediction polymarket trades¶
Show recent trades on a market.
bullpen prediction polymarket trades will-bitcoin-hit-100k
bullpen prediction polymarket trades will-bitcoin-hit-100k --limit 50
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
SLUG |
positional | Required. Market slug | |
--limit |
number | 20 |
Maximum number of trades |
bullpen prediction polymarket holders¶
Show top position holders for a market.
bullpen prediction polymarket holders will-bitcoin-hit-100k
bullpen prediction polymarket holders will-bitcoin-hit-100k --limit 10
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
SLUG |
positional | Required. Market slug | |
--limit |
number | 20 |
Maximum number of holders |
bullpen prediction polymarket limit-buy¶
Place a limit buy order on a prediction market outcome.
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
MARKET_SLUG |
positional | Required. Market slug | |
OUTCOME |
positional | Required. Outcome name | |
--price |
number | Required. Limit price (0.01–0.99) | |
--shares |
number | Required. Number of shares | |
--expiration |
gtc, eod |
gtc |
Order expiration |
--trade-server-url |
string | Required. Trade server URL (env: BULLPEN_TRADE_SERVER_URL) |
|
--access-token |
string | Required. Access token (env: BULLPEN_ACCESS_TOKEN) |
|
--address |
string | Required. Wallet address | |
--yes |
flag | Skip confirmation |
bullpen prediction polymarket limit-sell¶
Place a limit sell order on a prediction market outcome.
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
MARKET_SLUG |
positional | Required. Market slug | |
OUTCOME |
positional | Required. Outcome name | |
--price |
number | Required. Limit price (0.01–0.99) | |
--shares |
number | Required. Number of shares | |
--expiration |
gtc, eod |
gtc |
Order expiration |
--trade-server-url |
string | Required. Trade server URL (env: BULLPEN_TRADE_SERVER_URL) |
|
--access-token |
string | Required. Access token (env: BULLPEN_ACCESS_TOKEN) |
|
--address |
string | Required. Wallet address | |
--yes |
flag | Skip confirmation |
bullpen prediction polymarket leaderboard¶
View top traders on the Polymarket leaderboard.
bullpen prediction polymarket leaderboard
bullpen prediction polymarket leaderboard --period week --limit 10
| Flag | Type | Default | Description |
|---|---|---|---|
--period |
day, week, month, all |
all |
Time period |
--limit |
number | 25 |
Maximum number of traders |
bullpen prediction polymarket profile¶
View trader profile statistics.
bullpen prediction polymarket profile 0x1234...
bullpen prediction polymarket profile 0x1234... --trades
| Arg/Flag | Type | Description |
|---|---|---|
ADDRESS |
positional | Required. Wallet address |
--trades |
flag | Include recent trade history |
bullpen prediction polymarket smart-money¶
View smart money signals and top trader activity. Requires authentication.
bullpen prediction polymarket smart-money
bullpen prediction polymarket smart-money --type top_traders --category crypto
bullpen prediction polymarket smart-money --type new_wallet --limit 10
| Flag | Type | Default | Description |
|---|---|---|---|
--type |
aggregated, top_traders, new_wallet |
aggregated |
Signal type |
--category |
string | Category: politics, sports, crypto, culture, economics, tech, finance | |
--limit |
number | 20 |
Maximum number of results |
bullpen prediction polymarket comments [SLUG]¶
View comments on markets, events, series, or users. Also supports a smart-filtered feed.
bullpen prediction polymarket comments will-bitcoin-hit-100k
bullpen prediction polymarket comments my-event-slug --event
bullpen prediction polymarket comments --user 0x1234...
bullpen prediction polymarket comments will-bitcoin-hit-100k --replies <comment-id>
bullpen prediction polymarket comments --filtered --min-pnl 1000 --min-volume 50000
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
SLUG |
positional | Market/event/series slug (optional with --user or --filtered) |
|
--event |
flag | Treat slug as an event slug | |
--series |
flag | Treat slug as a series slug | |
--user |
string | Show comments by a specific address | |
--replies |
string | Show replies to a comment by comment ID | |
--filtered |
flag | Use smart-filtered comment feed | |
--page |
number | 1 |
Page number |
--limit |
number | 20 |
Results per page |
--min-pnl |
number | Minimum lifetime PnL (filtered mode) | |
--min-volume |
number | Minimum lifetime volume (filtered mode) | |
--min-predictions |
number | Minimum prediction count (filtered mode) | |
--category |
string | Filter by category (filtered mode) | |
--following-only |
flag | Only show comments from followed users (filtered mode) |
bullpen prediction polymarket feed <TYPE>¶
View a filtered trade or comment feed with trader quality controls.
bullpen prediction polymarket feed trades
bullpen prediction polymarket feed comments --min-pnl 5000 --category crypto
bullpen prediction polymarket feed trades --action Buy --min-trade-size 500 --min-pnl 10000
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
TYPE |
positional | Required. Feed type: trades or comments |
|
--min-pnl |
number | Minimum lifetime PnL | |
--min-volume |
number | Minimum lifetime volume | |
--min-predictions |
number | Minimum prediction count | |
--min-position-value |
number | Minimum position value | |
--category |
string | Filter by category | |
--following-only |
flag | Only following (comments feed only) | |
--action |
string | Trade action: All, Buy, Sell (trades feed only) |
|
--min-trade-size |
number | Minimum trade size in USD (trades feed only) | |
--min-price |
number | Minimum share price 0.01–0.99 (trades feed only) | |
--max-price |
number | Maximum share price 0.01–0.99 (trades feed only) | |
--exclude-categories |
string | Comma-separated list of categories to exclude | |
--page |
number | 1 |
Page number |
--limit |
number | 20 |
Results per page |
bullpen prediction polymarket comment-alert [--set|--delete]¶
View or manage comment alert settings. Without flags, shows the current alert. Requires authentication.
bullpen prediction polymarket comment-alert
bullpen prediction polymarket comment-alert --set --min-pnl 5000 --category crypto
bullpen prediction polymarket comment-alert --set --following-only
bullpen prediction polymarket comment-alert --delete
| Flag | Type | Description |
|---|---|---|
--set |
flag | Create or update the alert |
--delete |
flag | Delete the alert |
--min-pnl |
number | Minimum lifetime PnL |
--min-volume |
number | Minimum lifetime volume |
--min-predictions |
number | Minimum prediction count |
--min-position-value |
number | Minimum position value |
--min-position-size |
number | Minimum position size |
--category |
string | Filter by category |
--following-only |
flag | Only alert on comments from followed users |
--exclude-categories |
string | Comma-separated list of categories to exclude |
Note: --set and --delete are mutually exclusive.
bullpen prediction polymarket trade-alert [--set|--delete]¶
View or manage trade alert settings. Without flags, shows the current alert. Requires authentication.
bullpen prediction polymarket trade-alert
bullpen prediction polymarket trade-alert --set --min-pnl 10000 --action Buy
bullpen prediction polymarket trade-alert --set --min-trade-size 1000 --tracked-only
bullpen prediction polymarket trade-alert --delete
| Flag | Type | Description |
|---|---|---|
--set |
flag | Create or update the alert |
--delete |
flag | Delete the alert |
--min-pnl |
number | Minimum lifetime PnL |
--min-volume |
number | Minimum lifetime volume |
--min-predictions |
number | Minimum prediction count |
--min-position-value |
number | Minimum position value |
--category |
string | Filter by category |
--action |
string | Trade action: All, Buy, Sell |
--min-trade-size |
number | Minimum trade size in USD |
--min-price |
number | Minimum share price 0.01–0.99 |
--max-price |
number | Maximum share price 0.01–0.99 |
--tracked-only |
flag | Only alert on trades from tracked traders |
--exclude-categories |
string | Comma-separated list of categories to exclude |
Note: --set and --delete are mutually exclusive.
bullpen prediction polymarket smart-alerts [--set]¶
View or manage smart alert preferences. Without flags, shows current settings. Requires authentication.
bullpen prediction polymarket smart-alerts
bullpen prediction polymarket smart-alerts --set --categories crypto,politics --smart-money true
bullpen prediction polymarket smart-alerts --set --top-traders false --new-wallet true
| Flag | Type | Description |
|---|---|---|
--set |
flag | Update smart alert settings |
--categories |
string | Comma-separated preferred categories |
--smart-money |
bool | Enable/disable smart money alerts |
--new-wallet |
bool | Enable/disable new wallet alerts |
--top-traders |
bool | Enable/disable top traders alerts |
bullpen prediction polymarket track [ADDRESS]¶
Track or untrack Polymarket addresses, list tracked addresses, and view trades from tracked addresses.
bullpen prediction polymarket track 0x1234...
bullpen prediction polymarket track 0x1234... --untrack
bullpen prediction polymarket track 0x1234... --update-filters --notify-trades true --trade-threshold 500
bullpen prediction polymarket track --list
bullpen prediction polymarket track --trades
| Arg/Flag | Type | Default | Description |
|---|---|---|---|
ADDRESS |
positional | Address to track/untrack (optional with --list or --trades) |
|
--untrack |
flag | Untrack the specified address | |
--list |
flag | List all tracked addresses | |
--trades |
flag | Show recent trades from all tracked addresses | |
--update-filters |
flag | Update notification filters for the tracked address | |
--notify-comments |
bool | Enable/disable comment notifications | |
--notify-trades |
bool | Enable/disable trade notifications | |
--trade-threshold |
number | Minimum trade size in USD to trigger a notification | |
--markets |
string | Comma-separated list of market slugs to filter by | |
--category |
string | Filter by category | |
--min-position-size |
number | Minimum position size | |
--action |
string | Trade action: All, Buy, Sell |
|
--page |
number | 1 |
Page number |
--limit |
number | 20 |
Results per page |
Points & Rewards¶
bullpen points¶
View your total points and volume. Requires authentication.
| Flag | Type | Description |
|---|---|---|
--history |
flag | Include points distribution history |
bullpen rewards¶
View and claim rewards. Requires authentication.
| Flag | Type | Description |
|---|---|---|
--claim |
flag | Claim available rewards (requires confirmation) |
Notifications¶
bullpen notifications¶
View and manage notifications. Requires authentication.
| Flag | Type | Description |
|---|---|---|
--unread |
flag | Show only unread notifications |
--mark-read |
flag | Mark all notifications as read |
Wallet Tracking¶
bullpen wallet track¶
Start tracking a wallet address. Requires authentication.
bullpen wallet track 0x1234... --chain solana
bullpen wallet track 0x1234... --chain ethereum --nickname "My Wallet"
| Arg/Flag | Type | Description |
|---|---|---|
ADDRESS |
positional | Required. Wallet address to track |
--chain |
string | Required. Chain: solana, polygon, ethereum, arbitrum, hyperliquid (perps), hyperliquid_spot, bitcoin |
--nickname |
string | Optional nickname for the wallet |
bullpen wallet untrack¶
Stop tracking a wallet address. Requires authentication.
| Arg/Flag | Type | Description |
|---|---|---|
ADDRESS |
positional | Required. Wallet address to untrack |
--chain |
string | Required. Chain |
bullpen wallet tracked¶
List all tracked wallets. Requires authentication.
No flags.
Experimental Features¶
Experimental features are gated behind the [experimental] config section. All features default to disabled. Use the bullpen experimental commands to list, enable, or disable features.
bullpen experimental list¶
List all experimental features and their current status.
No flags.
bullpen experimental enable¶
Enable an experimental feature.
| Arg | Type | Description |
|---|---|---|
FEATURE |
positional | Required. Feature name (e.g., device_login) |
bullpen experimental disable¶
Disable an experimental feature.
| Arg | Type | Description |
|---|---|---|
FEATURE |
positional | Required. Feature name (e.g., device_login) |
Available experimental features:
| Feature | Description |
|---|---|
device_login |
Enable browser/device login flow (requires backend support) |
prediction_discovery |
Enable extra discovery lenses (sports, crypto, walletscope, pulse, traders, flow) |
prediction_analytics |
Enable market data + trader intelligence commands (search, event, trades, etc.) |
prediction_social |
Enable community features (comments, feed, alerts) |
Shell Completion¶
bullpen completion¶
Generate shell completion scripts.
bullpen completion bash > /etc/bash_completion.d/bullpen
bullpen completion zsh > ~/.zsh/completion/_bullpen
| Arg | Type | Description |
|---|---|---|
SHELL |
bash, zsh, fish, elvish, powershell |
Shell for completions |
Environment Variables¶
| Variable | Used By | Description |
|---|---|---|
BULLPEN_TRADE_SERVER_URL |
buy, sell, redeem, orders (cancel) | Trade server endpoint |
BULLPEN_ACCESS_TOKEN |
buy, sell, redeem, orders (cancel) | Authentication token for trade server |
BULLPEN_HOME |
all | Override config directory (default: ~/.bullpen) |
RUST_LOG |
all | Enable logging to ~/.bullpen/log/bullpen-cli.log (e.g., debug, bullpen_core=trace). Logging is disabled when unset |
BULLPEN_MANAGED_BY_NPM |
update checker | Set by npm wrapper; tells update checker to suggest npm upgrade |
BULLPEN_UPDATE_URL |
update checker | Override the GitHub Releases URL used for update checks (for testing) |