`bullpen doctor auth`¶

Last updated: July 13, 2026

Diagnose authentication state: token validity, onboarding, wallet, keypair, and bundle

Usage¶

bullpen doctor auth [OPTIONS]

Live Help¶

Diagnose authentication state: token validity, onboarding, wallet, keypair, and bundle

Usage: bullpen doctor auth [OPTIONS]

Options:
      --output <OUTPUT>
          Output format for command results

          [possible values: table, json]

      --refresh
          Refresh the cached Bullpen access token before reporting diagnostics.

          Uses the stored refresh token and the normal credential refresh lock. Does not start device login, create keypairs, or repair/delete files.

      --env <ENV>
          Target environment to connect to (overrides config.toml)

          [env: BULLPEN_ENV=]
          [possible values: staging, production]

      --repair
          Attempt to repair detected credential corruption.

          Backs up the corrupt file to <path>.bak.<unix-timestamp>, deletes it, and instructs the user to run `bullpen login` to re-establish credentials. Requires typing REPAIR (all caps) to confirm. No-op when no recoverable corruption is detected.

      --config <CONFIG>
          Path to a custom config.toml file (overrides $BULLPEN_CONFIG and the default location).

          Explicit --config and BULLPEN_CONFIG paths fail closed: if the file is missing, the CLI exits validation instead of silently loading defaults. Credentials still resolve via BULLPEN_HOME, so set BULLPEN_HOME too when isolating a session.

      --yes
          Required confirmation flag for --repair (alongside the typed REPAIR prompt). Without --yes, --repair will refuse to proceed with the destructive operation

      --read-only
          Enable read-only mode: blocks all mutating commands

      --non-interactive
          Suppress interactive prompts; does NOT imply --yes for money-moving commands

          [env: BULLPEN_NON_INTERACTIVE=]

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # Inspect local auth state before opening a support ticket
  bullpen doctor auth

  # Export auth diagnostics as JSON for support
  bullpen doctor auth --output json

Without --refresh or --repair, bullpen doctor auth is read-only. It does not
refresh tokens, start device login, save credentials, clear files, create
keypairs, or repair local auth state.

Example Commands¶

bullpen doctor auth
bullpen doctor auth --output json

JSON Output¶

Contract: JSON Output Contract.

Successful output is a single JSON document. The shape below is representative for this command family; commands may add fields without breaking the shared contract.

Schema version: 1 when a command emits schema_version; otherwise treat the current command shape as contract version 1.

Top-level Keys¶

key	type	nullable	notes
`status`	string	no	Diagnostic status, commonly `ok`, `warning`, or `error`
`error_code`	string	yes	Stable support code when the diagnostic found an auth problem
`credentials_valid`	boolean	no	Whether local credentials can be loaded
`credentials_error`	string	yes	Local credential load/decrypt error, if available
`token_valid`	boolean	no	Whether the access token is currently valid
`token_expires_in_secs`	integer	yes	Access-token TTL in seconds when known
`refresh_attempted`	boolean	no	Whether this run attempted an explicit token refresh via `--refresh`
`refresh_succeeded`	boolean	yes	Whether the explicit refresh succeeded; present only when `refresh_attempted` is true
`refresh_error`	string	yes	Redacted refresh failure detail; present only when an explicit refresh failed
`refresh_token_expires_in_secs`	integer	yes	Refresh-token TTL in seconds when known
`keypair_valid`	boolean	no	Whether the Turnkey keypair is usable
`wallet_ready`	boolean	no	Whether wallet routing is ready for trading
`onboarding_complete`	boolean	no	Whether server-side onboarding is complete
`trade_auth_state`	string	no	Normalized trade-auth state, such as `ready` or `reauthentication_required`
`trade_auth_blocked`	boolean	no	Whether authenticated trading is currently blocked
`trade_auth_blocker_reason`	string	yes	Human-readable blocker reason
`turnkey_signing_session_present`	boolean	no	Whether a Turnkey signing session is cached
`turnkey_signing_session_expired`	boolean	no	Whether the cached Turnkey signing session is expired
`pending_actions`	array	no	Support-safe remediation actions the user should complete
`recovery_methods`	array	no	Recovery methods known to the server
`remediation`	object	yes	Next recommended command and explanation

Example¶

Example JSON output

bullpen doctor auth --output json

{
  "bundle_decryptable": null,
  "cli_api_key_metadata_present": false,
  "cli_api_key_rotation_due": false,
  "cli_api_key_state": "missing",
  "credential_storage": {
    "backend": "file",
    "credentials_lock_present": false,
    "encrypted_credentials_present": false,
    "format": "none",
    "plaintext_credentials_present": false
  },
  "credentials_error": null,
  "credentials_valid": false,
  "error_code": "AUTH_REAUTHENTICATION_REQUIRED",
  "keypair_valid": false,
  "onboarding_complete": false,
  "pending_actions": [],
  "recovery_methods": [],
  "refresh_attempted": false,
  "refresh_token_expires_in_secs": null,
  "remediation": {
    "action": "reauthenticate",
    "command": "bullpen login",
    "message": "Refresh local Bullpen and Turnkey credentials, then retry the real trade."
  },
  "server_time_offset_ms": 202,
  "session_recovery": {
    "code": "auth_login_required",
    "next_command": "bullpen login",
    "requires_login": true,
    "safe_to_retry": false,
    "state": "login_required"
  },
  "status": "error",
  "token_expires_in_secs": null,
  "token_valid": false,
  "trade_auth_blocked": true,
  "trade_auth_blocker_reason": "No local Bullpen session is available.",
  "trade_auth_state": "reauthentication_required",
  "turnkey_signing_session_expired": false,
  "turnkey_signing_session_present": false,
  "wallet_ready": false
}

Stability¶

Patch releases may add nullable or optional fields. Minor releases may add required fields or increment schema_version. Major releases may remove or rename fields.

bullpen doctor auth¶