`bullpen doctor auth`¶

Last updated: August 26, 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¶

State change: One or more examples below change account or trading state. Run only the command that matches your intended action.

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: 2 for bullpen doctor auth JSON output.

Top-level Keys¶

key	type	nullable	notes
`schema_version`	integer	no	Always present; auth diagnostic schema version, exactly `2`
`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	Always present; whether local credentials can be loaded
`credential_storage`	object	no	Always present; support-safe credential-store backend and file-presence summary
`credentials_error`	string	yes	Local credential load/decrypt error, if available
`token_valid`	boolean	no	Always present; whether the access token is currently valid
`token_expires_in_secs`	integer	yes	Access-token TTL in seconds when known
`refresh_attempted`	boolean	no	Always present; 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
`network_refresh_performed`	boolean	yes	Present only for `--refresh`; whether the command performed a network refresh
`access_token_source`	string or null	yes	Present only for `--refresh`; one of `cached`, `disk_reconciled`, `network_refreshed`, or null
`refresh_mode`	string	yes	Present only for `--refresh`; current value is `ensure_usable_access_token`
`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_checked`	boolean	no	Always present; whether this run actually checked the Turnkey keypair
`keypair_valid`	boolean	no	Always present compatibility shim; when `keypair_checked=false`, this is always `false` and does not mean the keypair is invalid
`keypair_error`	string or null	yes	Always present; Turnkey keypair check error, or null when unchecked/no error
`bundle_decryptable`	boolean	yes	Whether the Turnkey bundle decrypted; null when unchecked
`wallet_ready`	boolean	no	Always present; whether wallet routing is ready for trading
`onboarding_complete`	boolean	no	Always present; whether server-side onboarding is complete
`trade_auth_state`	string	no	Always present; normalized trade-auth state, such as `ready` or `reauthentication_required`
`trade_auth_blocked`	boolean	no	Always present; whether authenticated trading is currently blocked
`trade_auth_blocker_reason`	string	yes	Human-readable blocker reason
`turnkey_signing_session_present`	boolean	no	Always present; whether a Turnkey signing session is cached
`turnkey_signing_session_expired`	boolean	no	Always present; whether the cached Turnkey signing session is expired
`signing_capability`	object	no	Always present; passive diagnostics set `checked: false`, `signing_capability: "unknown"`, and `reason: "doctor_auth_passive_does_not_check_signing_capability"`
`pending_actions`	array	no	Always present; support-safe remediation actions the user should complete
`recovery_methods`	array	no	Always present; recovery methods known to the server
`session_recovery`	object or null	yes	Always present; support-safe login/session recovery state, or null when no recovery action is required
`remediation`	object	yes	Next recommended command and explanation

Example¶

Example output: This non-runnable command-and-response pair documents the JSON shape. Use the preview/live workflow in Example Commands when you intend to submit.

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_checked": false,
  "keypair_error": null,
  "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"
  },
  "schema_version": 2,
  "signing_capability": {
    "checked": false,
    "next_action": "none",
    "reason": "doctor_auth_passive_does_not_check_signing_capability",
    "resolution_owner": "not_checked",
    "safe_to_retry": false,
    "signer_source": "turnkey_disabled",
    "signing_capability": "unknown",
    "support_safe": true
  },
  "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¶