Configuration¶

Use this page to understand where Bullpen reads configuration from, how command line overrides interact with environment variables, and how to isolate profiles for testing or automation.

Files And Directories¶

Bullpen's default data directory is ~/.bullpen.

Path	Purpose
`~/.bullpen/config.toml`	Main CLI configuration
`~/.bullpen/credentials.json.enc`	Encrypted local credentials
`~/.bullpen/keys/`	Local key material used by supported flows
`~/.bullpen/log/bullpen-cli.log`	File logs when `RUST_LOG` is enabled

Create a default config:

bullpen config init

Inspect effective config without printing secrets:

bullpen config show

For exact flags and JSON output fields, use the generated config init and config show pages.

Precedence¶

Use the most local control for one-off commands and environment variables for repeatable automation.

Scope	Control	Notes
Command line	`--config <path>`	Chooses the config file for this invocation. Explicit paths fail closed when missing.
Environment	`BULLPEN_CONFIG`	Chooses the config file when `--config` is absent. Explicit paths fail closed when missing.
Default	`$BULLPEN_HOME/config.toml` or `~/.bullpen/config.toml`	Used when no explicit config path is set.
Command line	`--env staging\|production`	Overrides the target environment for this invocation.
Environment	`BULLPEN_ENV=staging\|production`	Sets the target environment when `--env` is absent.
Command line	`--read-only`	Blocks mutating commands for this invocation.
Environment	`BULLPEN_READ_ONLY=1`	Blocks mutating commands for the process environment.
Command line	`--non-interactive`	Suppresses prompts but does not imply `--yes`.
Environment	`BULLPEN_NON_INTERACTIVE=1`	Suppresses prompts for automation. It still does not imply `--yes`.

Credentials resolve through BULLPEN_HOME, not only through --config. When you isolate a local support or CI profile, set both:

export BULLPEN_HOME="$PWD/.bullpen-ci-home"
export BULLPEN_CONFIG="$BULLPEN_HOME/config.toml"
bullpen config init

For unattended bots, containers, cron, and systemd, use an absolute BULLPEN_HOME such as /var/lib/bullpen-bot. Relative values are rejected because they can resolve differently between shells and supervisors.

Then inspect the isolated config before login or trading:

bullpen config show --output json
bullpen status --output json

If BULLPEN_CONFIG points to a missing file, Bullpen fails closed instead of falling back to ~/.bullpen/config.toml. Create the config file first, or unset BULLPEN_CONFIG when you want the default profile.

Common Environment Variables¶

Variable	Purpose
`BULLPEN_HOME`	Override Bullpen's data directory
`BULLPEN_CONFIG`	Override the config file path
`BULLPEN_ENV`	Select `staging` or `production`
`BULLPEN_READ_ONLY`	Block mutating commands globally
`BULLPEN_NON_INTERACTIVE`	Suppress prompts without granting submit approval
`BULLPEN_DISABLE_TELEMETRY`	Opt out of Sentry errors and anonymous usage analytics
`BULLPEN_GITHUB_TOKEN`	Avoid anonymous GitHub API rate limits during upgrade checks
`BULLPEN_POLYGON_RPC_URL`	Override Polygon RPC for supported diagnostics and relayer preflight reads
`BULLPEN_ARBITRUM_RPC_URL`	Override Arbitrum RPC for Hyperliquid deposit helpers
`BULLPEN_SOLANA_RPC_URL`	Override Solana RPC

The generated command reference lists all documented environment variables for the installed CLI version.

Profile Isolation Tasks¶

Use isolated profiles for support reproduction, CI, or separating production and staging state. Keep credentials, config, and logs in the same directory unless a support runbook says otherwise.

Create A Fresh Local Profile¶

This creates a separate profile without touching the default ~/.bullpen directory:

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

Run bullpen login only after config show confirms the expected profile.

Run Read-Only Diagnostics From An Isolated Profile¶

Use read-only and non-interactive mode when you are collecting support evidence or testing automation defaults:

export BULLPEN_HOME="$PWD/.bullpen-support-home"
export BULLPEN_CONFIG="$BULLPEN_HOME/config.toml"
export BULLPEN_READ_ONLY=1
export BULLPEN_NON_INTERACTIVE=1
bullpen status --output json
bullpen doctor auth --output json

BULLPEN_READ_ONLY=1 blocks mutating commands. BULLPEN_NON_INTERACTIVE=1 suppresses prompts but does not grant confirmation for live actions.

Use A One-Off Config File¶

Use --config <path> for one command when you already have a config file at that path:

bullpen --config "$PWD/.bullpen-support-home/config.toml" config show --output json

This does not move credentials by itself. Set BULLPEN_HOME too when the command must use a different credential bundle.

Automation Defaults¶

For agents and CI jobs:

export BULLPEN_READ_ONLY=1
export BULLPEN_NON_INTERACTIVE=1
bullpen status --output json
bullpen portfolio balances --output json

BULLPEN_READ_ONLY=1 blocks mutating commands. BULLPEN_NON_INTERACTIVE=1 prevents prompts but does not approve money movement. Live money-moving commands still require command-specific confirmation such as --yes.

Telemetry¶

Use bullpen config telemetry to inspect or change telemetry settings through the supported config interface. Use BULLPEN_DISABLE_TELEMETRY=1 for a process or shell-wide opt-out.

See Telemetry for what Bullpen collects, what it never sends, and how local logs work.