Auth And Config Recovery

Purpose

Use this guide when login works on one machine but not another, a support run uses the wrong Bullpen profile, copied credentials fail to decrypt, or auth diagnostics mention missing local credential files. Start with read-only diagnostics and generated command references before removing local state.

This guide covers local auth and profile recovery only. It does not repair server-side account, KYC, wallet-routing, or funds state.

Before You Start

• Run every command from the same shell, machine, and Bullpen account that saw the failure.
• Do not delete ~/.bullpen as the first recovery step. It can remove config, logs, local keys, and wallet-routing evidence.
• Do not copy or paste private keys, seed phrases, JWTs, API tokens, credentials.json.enc, or full config files into support tickets.
• Set both BULLPEN_HOME and BULLPEN_CONFIG when isolating a support or CI profile. Setting only one can mix credentials from one profile with config from another.

Safe First Command

Run auth and config diagnostics before login or local reset. Both commands are read-only.

bullpen doctor auth --output json
bullpen config show --output json

doctor auth reports token health, onboarding state, wallet readiness, local credential-file health, and a credential_storage object. The storage object is non-mutating and helps support distinguish encrypted credentials, legacy plaintext credentials, both files, no local credentials, and ephemeral test stores without decrypting or rewriting local auth files. config show reports effective config without printing secrets. See the generated doctor auth and config show references for exact flags.

A logged-in session is three credentials with different lifetimes: the JWT access token (~15 minutes, auto-refreshed), the refresh token (~30 days), and the signing session (~7 days). A normal access-token expiry should refresh automatically. Run bullpen login only when diagnostics report that the refresh token was rejected or the signing session must be renewed. Do not delete local state unless the CLI explicitly identifies unrecoverable credential storage. If a command fails during a transient refresh, run bullpen fix --refresh once and follow its single next action.

Newer builds also include nullable session_recovery metadata on bullpen status --output json and bullpen doctor auth --output json. When it is present, branch on session_recovery.code, requires_login, safe_to_retry, and next_command. Do not start login, forced logout, or file cleanup from prose alone.

Example output

$ bullpen doctor auth --output json

{
  "status": "error",
  "error_code": "AUTH_REAUTHENTICATION_REQUIRED",
  "credentials_valid": true,
  "token_valid": false,
  "token_expires_in_secs": null,
  "refresh_token_expires_in_secs": null,
  "keypair_valid": true,
  "wallet_ready": false,
  "trade_auth_state": "reauthentication_required",
  "trade_auth_blocked": true,
  "trade_auth_blocker_reason": "No local Bullpen session is available.",
  "turnkey_signing_session_present": true,
  "turnkey_signing_session_expired": true,
  "session_recovery": {
    "state": "login_required",
    "code": "auth_login_required",
    "requires_login": true,
    "safe_to_retry": false,
    "next_command": "bullpen login"
  },
  "remediation": {
    "action": "reauthenticate",
    "command": "bullpen login",
    "message": "Refresh local Bullpen and Turnkey credentials, then retry the real trade."
  }
}

If the issue involves a copied headless profile, run the deployment diagnostic from the destination machine too.

bullpen doctor deploy-auth --output json

See the generated doctor deploy-auth reference.

Choose The Recovery Path

Use the smallest recovery action that matches the diagnostic result.

Diagnostic result	Next safe action
You are not logged in, the device code expired, or the browser did not open	Run bullpen login or bullpen login --no-browser.
You were away and signing/trading now fails, or turnkey_signing_session_expired is true	Run bullpen login to mint a fresh session. The refresh token (~30 days) or Turnkey signing session (~7 days) expired. Do not delete ~/.bullpen first.
credentials.json.enc or credential_salt.bin is missing or corrupt	Run bullpen login; it moves unreadable local auth files aside and starts a fresh session. Run bullpen doctor auth --output json first if you need support to inspect copied-home state.
You choose to reset unrecoverable local auth state	Run bullpen logout --force && bullpen login as the last-resort local reset.
doctor auth says local keypair repair is applicable	Run bullpen doctor auth --repair --yes only after saving the read-only JSON.
The command is using the wrong account, environment, or config file	Create or inspect an isolated profile with both BULLPEN_HOME and BULLPEN_CONFIG.
A partial copied credential bundle, changed absolute home, or username mismatch is blocking unattended deployment	Restore the complete source bundle or re-login on the destination machine; do not keep copying partial auth files.

For copied homes, confirm that credentials.json.enc, credential_salt.bin, and keys/ came from the same source profile. Use the same absolute BULLPEN_HOME and the same BULLPEN_USERNAME_OVERRIDE on both machines, then run bullpen doctor deploy-auth --output json on the destination host before running unattended commands.

Use a local persistent filesystem for copied-home auth. NFS mounts, cloud-synced folders, and container volumes are not validated for release by the source tests alone. doctor deploy-auth and the read-only auth smoke are necessary diagnostics for that exact runtime, not proof that every NFS/cloud-sync/container lock and fsync behavior is safe. If the path, username component, or bundled files differ, create a fresh login on the destination host instead of trying to repair pieces independently.

Use the generated login, logout, and doctor auth references before running a destructive reset.

For deterministic CI or release smoke runs, set BULLPEN_DISABLE_UPDATE_CHECK=1 before read-only diagnostics. This disables the background update-check cache write only; it does not change credential loading, refresh, or trading behavior.

Isolate A Support Profile

Create a profile that keeps config, credentials, and logs together. This does not touch the default ~/.bullpen profile.

export BULLPEN_HOME="$PWD/.bullpen-support-home"
export BULLPEN_CONFIG="$BULLPEN_HOME/config.toml"
mkdir -p "$BULLPEN_HOME"
bullpen config init
bullpen config show --output json

Label: configure. config init writes a local config file in the isolated profile. It does not log in or move funds. If BULLPEN_CONFIG points to a missing file, Bullpen fails closed instead of silently using the default profile.

After config show confirms the expected path, log in to that profile.

bullpen login --no-browser
bullpen doctor auth --output json

Use --no-browser when the login browser is on a different machine or when you need to copy the device-code URL into an existing browser session.

Local Reset Boundaries

Local reset commands only affect files on the current machine and profile. They do not repair server-side account state, wallet routing, missing deposits, or trading permissions.

Run a normal logout when the credential store is readable.

bullpen logout

Label: destructive local reset. This removes local credentials for the active profile.

Use forced logout only as a last-resort local reset after bullpen login cannot move unreadable local auth aside or support asks for a full local reset.

bullpen logout --force

Label: destructive local reset. This clears local auth files before a fresh login. Keep doctor auth --output json output before running it when possible.

When you need a support-safe machine-readable reset report, use bullpen logout --force --output json. The JSON report returns top-level server_warning and force_wipe fields, redacts local absolute paths, and marks the reset as destructive.

Use auth repair only when the diagnostic output names that repair.

bullpen doctor auth --repair --yes

Label: destructive, support-facing. This backs up and removes a corrupt local keypair file when doctor auth says the repair is applicable. It is not the generic fix for missing encrypted credentials or missing salt files.

Support Capture

For support tickets, include sanitized output from the failing profile:

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

If the issue involves copied credentials or a headless host, include:

bullpen doctor deploy-auth --output json

Do not attach secrets, full config files, full logs, credential files, key directories, JWTs, or private keys. If support needs wallet-routing or funds evidence too, switch to the Wallet Routing And Funds Recovery guide.

See Also

• Authentication
• Configuration
• Troubleshooting and Support
• Headless & Docker Setup
• JSON Output Contract
• Command Reference: doctor
• Command Reference: config