Authentication¶

Use this page when you are setting up Bullpen for the first time, checking whether a session is still valid, or collecting auth diagnostics for support.

Bullpen uses browser-based device login.

Start with passive diagnostics when you are not sure whether you are already logged in.

bullpen status --output json
bullpen doctor auth --output json

bullpen status shows the installed version, environment, login state, and basic local session evidence. It is passive and does not refresh remote account or wallet evidence. doctor auth --output json returns support-friendly JSON for session state, missing local files, incomplete account state, and credential-storage problems. It does not start browser login, repair files, refresh tokens, or change wallet routing.

Both commands may include a nullable session_recovery object. When present, branch on session_recovery.code, requires_login, safe_to_retry, and next_command. Do not start login, forced logout, or local file cleanup from human prose alone.

Run bullpen login only when diagnostics show no usable session or report a login-required state. The CLI prints a URL and code. Open the URL, enter the code, and finish login in the browser. The CLI stores the resulting credentials under your Bullpen data directory. It does not require you to paste secrets back into the terminal.

If the browser cannot open on the same machine and diagnostics require login, run bullpen login --no-browser and complete the device-code flow from another browser.

If an older local install cannot read its saved login, run bullpen status --output json and bullpen doctor auth --output json first, and preserve the output if you need support. Run bullpen doctor auth --refresh --output json only when stale or expired session evidence is needed. Run bullpen login only when the diagnostic JSON says login is required or local credential recovery needs a fresh session. Use bullpen logout --force only as a last-resort local reset, then start a fresh login only when diagnostics require it.

When An Auth Attempt Does Not Finish¶

Device login and email verification errors can include an auth_incident object. Use its fields instead of repeating login:

attempt_id identifies this local CLI attempt.
stage shows where the attempt stopped, such as browser approval or email verification.
safe_to_retry states whether repeating the same operation is safe.
resolution_owner and next_command identify who can act and the one safe command to run next.
support_code and support_safe_evidence contain redacted evidence that is preserved in the next bullpen support bundle --output json artifact.

If safe_to_retry is false and next_command is bullpen support, do not request another email code or repeat login. For a passive redacted artifact, run bullpen support bundle --output json and attach the generated JSON file to your support ticket. The artifact remains on your machine until you attach it. Use plain bullpen support only when you want the interactive support flow.

Session Model And Expiry¶

Bullpen keeps your login local and refreshes short-lived session material when it can. Some authorizations expire sooner than others, so read-only commands may still work after trading or signing commands start failing.

The common "I was away and now trading fails" case is an expired session. Run bullpen status --output json and bullpen doctor auth --refresh --output json to confirm whether refresh succeeds. Run bullpen login only when the diagnostic JSON says login is required. You do not need to delete ~/.bullpen first.

Normal Customer Trading Auth¶

Normal customer trading uses your Bullpen login. You do not need to configure separate trading API keys for ordinary Polymarket orders.

Polymarket buy/sell/limit commands submit through Bullpen with your authenticated session. The CLI may refresh an expired session once only when it can reuse the same order body and idempotency key. Other write failures require the command's structured retry fields or fresh diagnostics before repeating.

If account wallet evidence is inconsistent, money-moving commands fail closed and ask for diagnostics. Run bullpen status --output json and bullpen doctor auth --refresh --output json before starting a new login flow. Login refreshes local auth only; it does not repair wallet routing.

Hyperliquid trading uses wallet signing for normal order flows. Hyperliquid agent-wallet management is separate and should be used only when a command explicitly asks for it.

Credential Storage And Isolation¶

By default, Bullpen stores local configuration and credentials under ~/.bullpen.

Use the default profile for the official release binary unless you deliberately override it. Run locally built or development binaries with a separate BULLPEN_HOME so dev tests do not rewrite your default ~/.bullpen credentials. Opt in to the default profile only when you intentionally want the local/dev binary to use the same credential home as the official release.

Control	Purpose
`BULLPEN_HOME`	Override the Bullpen data directory. Credentials still resolve through this directory.
`--config <path>`	Use a specific `config.toml`. The path fails closed if it does not exist.
`BULLPEN_CONFIG`	Use a specific config file path when `--config` is not provided. The path fails closed if it does not exist.

The encrypted credential bundle is local state. Copying only one credential file to another machine or another BULLPEN_HOME is not a portable login backup.

status --output json and doctor auth --output json include a credential_storage object. Use it to distinguish encrypted credentials, legacy plaintext credentials, both files, no local credentials, and ephemeral test stores without decrypting or rewriting the credential files.

When isolating a test account or CI run, set both BULLPEN_HOME and BULLPEN_CONFIG so config and credentials stay together. This is a non-runnable sequence: run config init only when creating that isolated profile, and run login only when the diagnostics require it.

export BULLPEN_HOME="$PWD/.bullpen-test-home"
export BULLPEN_CONFIG="$BULLPEN_HOME/config.toml"
bullpen config init
bullpen status --output json
bullpen doctor auth --output json

For unattended bots and copied credential homes, use an absolute BULLPEN_HOME such as /var/lib/bullpen-bot. Relative values are rejected because they can point at different profiles under cron, systemd, Docker, or CI runners.

For unattended auth, use a local persistent filesystem and run bullpen status --output json plus bullpen doctor auth --output json in the same runtime environment before any account or trading command. Do not assume copied credentials are portable across a different home path, username, or partially synced directory.

Keep the Bullpen home writable. Auth refresh is treated as successful only when the refreshed credentials are durably saved; if the CLI cannot persist the rotated session, it fails closed with a storage-focused error instead of silently leaving the next bot process with stale credentials.

A refresh response must include a non-empty access_token and a non-empty refresh_token. If either token is missing or empty, the CLI fails closed as AUTH_REFRESH_PERSISTENCE_FAILED, does not advance the in-process bearer token, and leaves the old on-disk credentials untouched. Keep the credential files in place for storage/service diagnostics and run bullpen status --output json plus bullpen doctor auth --output json before deciding whether login is required. Use bullpen doctor auth --refresh --output json only when the diagnostic or support path needs refreshed auth evidence.

Use bullpen status --output json and bullpen doctor auth --output json inside the same environment block before running account or trading commands from the isolated profile. Add --refresh only when stale or expired session evidence is needed.

For deterministic CI or release smoke runs that must not write the update-check cache, set BULLPEN_DISABLE_UPDATE_CHECK=1. This disables the background update checker only; it does not change auth, trading, or credential behavior.

Use the smallest next step that matches the symptom.

Symptom	Safe next step	Notes
You are unsure which account or environment is active	`bullpen status --output json`, then `bullpen doctor auth --output json`	Confirms local status and auth diagnostics without refreshing.
Diagnostics require login and the browser did not open or is on another machine	`bullpen login --no-browser`	Prints the verification URL and device code.
Diagnostics require login or the current device code expired	`bullpen login`	Starts a fresh device-code login.
Login polling stops with `auth_incident.next_command: "bullpen support"`	`bullpen support bundle --output json`	Do not repeat login for the same attempt. Attach the generated local JSON artifact.
Email verification stops at `email_otp_request` or reports an unknown outcome	`bullpen support bundle --output json`	The CLI did not replay the code request. Do not request another code until support inspects the attempt.
You were away and trading/signing now fails	`bullpen status --output json`, then `bullpen doctor auth --refresh --output json`	Run `bullpen login` only when diagnostics say login is required.
Auth diagnostics mention missing or corrupt saved credentials	`bullpen status --output json`, then `bullpen doctor auth --output json`	Run `bullpen login` only when diagnostics require a fresh session; login moves unreadable local auth files aside before re-authenticating. Use refresh only if the diagnostic or support path asks for it.
You choose to reset unrecoverable local auth state	`bullpen logout --force`	Last-resort destructive local reset. Start a fresh login afterward only when diagnostics require it.
`doctor auth` says local signing repair is applicable	`bullpen doctor auth --repair --yes`	Destructive local repair. Use only when the diagnostic output names this repair.
`doctor auth` reports incomplete account state after a fresh login	`bullpen verify-email`	Safe account-completion step; see the generated reference for exact options.

Do not delete the whole Bullpen home directory as the first fix. That can remove logs, config, local keys, and wallet-routing evidence that support may need.

Recovery Commands¶

Use the smallest recovery command that matches the failure. For account-level recovery, prefer the recovery_plan object when bullpen fix --refresh, bullpen recover polymarket --refresh --output json, or bullpen support bundle --output json emits it. For auth-attempt failures, prefer auth_incident. Do not combine rows from this table into a custom reset sequence.

Situation	Command
Check current auth state	`bullpen status --output json`, then `bullpen doctor auth --output json`
Re-run ordinary device-code login	`bullpen login` only when diagnostics require login
Refresh an expired session after time away	`bullpen doctor auth --refresh --output json`; run `bullpen login` only when diagnostics require login
Clear local credentials	`bullpen logout`
Clear corrupted local credentials when normal logout cannot load them	`bullpen logout --force`
Back up and remove corrupt local signing state when `doctor auth` says repair is applicable	`bullpen doctor auth --repair --yes`
Verify email if account access is incomplete	`bullpen verify-email`
Confirm installed version and platform gates	`bullpen status --output json`

bullpen doctor auth --repair --yes is destructive and support-facing: it backs up and removes corrupt local signing state only when the diagnostic says that repair is applicable, and still requires the typed REPAIR confirmation prompt. Use bullpen status --output json and read-only doctor auth --output json first. Use doctor auth --refresh --output json only for expired/stale session checks or when diagnostics request refreshed evidence before a login decision. Missing or corrupt saved credentials use the login recovery path above only when diagnostics require it.

bullpen logout --force --output json returns a top-level server_warning field plus a force_wipe object. The JSON redacts local absolute paths while still marking the operation as destructive. Human output still names the local files it is clearing for the current machine, but support tickets should prefer the JSON form when path disclosure is not needed.

Do not delete ~/.bullpen as the first recovery step. That also removes local config, keys, and logs that may help support diagnose the issue.

Support Capture¶

For support tickets, include command output from the same machine and account that saw the failure. Use refreshed auth diagnostics only when refreshed evidence is needed for the support case.

bullpen --version
bullpen status --output json
bullpen doctor auth --output json

Do not share private keys, seed phrases, session tokens, API tokens, full config files, or unredacted logs.