Bullpen TUI Guide¶

What is the TUI?¶

The TUI is Bullpen's full-screen terminal interface. Launch it when you want an interactive workspace for checking status, browsing markets, running trading commands, and watching output without retyping bullpen before every command.

Use one-shot CLI commands for scripts and pipes. Use bullpen shell if you want a readline REPL instead of a full-screen interface.

Launching¶

bullpen

The TUI requires a real terminal on stdout. If stdout is redirected, for example bullpen > out.txt, Bullpen exits cleanly and prints TUI requires a TTY on stdout to stderr. If stdin is piped, Bullpen prints top-level help instead of trying to launch the TUI.

Startup is passive: the TUI checks only local status and does not start device auth automatically. If you are not logged in, start device auth explicitly:

/login

Complete login in the browser. After /login, the TUI waits for the device-auth result and then fetches your portfolio. Press Ctrl+C while login is waiting to cancel the attempt. You can still exit with Ctrl+D and run bullpen login in a normal terminal if your terminal or browser cannot open the device-auth URL.

Local development builds refuse to write credentials into the default ~/.bullpen home because official release binaries use a different credential encryption secret. If a local build shows that warning, rerun it with an isolated home:

BULLPEN_HOME="$PWD/.bullpen-tui-auth-test" target/debug/bullpen --env production

Main screen layout¶

+-- Bullpen CLI v0.1.NN --------------------------------+
|                                                       |
|  output area                                         |
|  command results and status                          |
|  scroll with Shift+Up/PageUp                         |
|                                                       |
+-------------------------------------------------------+
| status bar: current action and key hints              |
+-------------------------------------------------------+
| > command input with slash-command autocomplete       |
+-------------------------------------------------------+

The normal screen waits for input. During command execution and device auth, the input line shows progress.

Bot operator panels and bot-control key bindings are preview features. They are only available in binaries built with the agent-preview feature, which is off in the default official release artifact.

Key bindings¶

Key	Action
`Enter`	Submit the current command. If the popup is open, accept the selected leaf command and submit it, or accept a group command and show its children.
`Tab`	Accept the highlighted autocomplete suggestion when the popup is open.
`Up` / `Down`	Move through input history, or move through popup choices when the popup is open.
`Shift+Up` / `Shift+Down`	Scroll the output area by one line.
`PageUp` / `PageDown`	Scroll the output area by half a screen.
`Left` / `Right`	Move the cursor in the input line.
`Alt+Left` / `Alt+Right`	Move the cursor by word.
`Home` / `Ctrl+A`	Jump to the start of the input line.
`End` / `Ctrl+E`	Jump to the end of the input line.
`Backspace` / `Delete`	Delete one character.
`Esc`	Close the popup, or clear the input line if no popup is open.
`Ctrl+C`	Copy and clear the active text selection; otherwise clear non-empty input; otherwise exit.
`Ctrl+D`	Exit the TUI.

Preview builds with agent-preview also expose these bot-operator keys when an operator panel is active:

Key	Action
`F6`	Pause the active bot run.
`F7`	Resume the active bot run.
`F8`	Approve the active bot request.

Slash commands¶

Start commands with /. Typing / opens the autocomplete popup; keep typing to filter the current level. Examples:

/status
/portfolio balances
/polymarket discover --limit 5
/polymarket buy will-ronaldo-cry-at-the-world-cup-20260604013616610 No 10 --max-price 0.01 --preview

Submitting a command group such as /polymarket shows its available child commands. The TUI command tree mirrors the main CLI namespaces for account, portfolio, Polymarket, Hyperliquid, and Solana. Preview builds with agent-preview may also expose bot workflows. The popup is the source of truth for what is available in the current build.

Escape routes¶

Exit the TUI with Ctrl+D, or with Ctrl+C on an empty input line.
Close a stuck autocomplete popup with Esc.
Clear a partially typed command with Ctrl+C or Esc.
Run a command outside the TUI with bullpen <command>.
Use the readline REPL with bullpen shell.
Print command-line help with bullpen --help.

Mouse¶

Mouse capture is enabled. Use the scroll wheel over the output area to scroll. Drag in the output area to select text; releasing the mouse copies the selected text when the clipboard is available. Preview builds with agent-preview may expose clickable operator-panel actions when the panel is visible.

TUI vs shell vs one-shot CLI¶

Mode	Start with	Use when
TUI	`bullpen`	You want a full-screen workspace, autocomplete popup, and scrollback.
Shell	`bullpen shell`	You want a lightweight REPL with command history but no full-screen UI.
One-shot CLI	`bullpen <command>`	You are scripting, piping output, using `--output json`, or running one command at a time.