feat(config): follow XDG Base Directory spec for config location

[jared-outpost]

Closes #1502

What

sentry-cli stored its config/data (the cli.db SQLite database with credentials and caches) in ~/.sentry, cluttering the home directory and breaking in environments that block writes to $HOME (e.g. sandboxed coding agents).

This makes the config directory follow the XDG Base Directory specification, matching how the CLI already resolves shell/completion paths.

Resolution precedence

getConfigDir() now resolves via a new pure resolveConfigDir(env, home) helper:

1. SENTRY_CONFIG_DIR — explicit override, unchanged (highest priority)
2. Legacy ~/.sentry — used when it already exists, so existing installs keep working with no migration
3. $XDG_CONFIG_HOME/sentry — defaulting to ~/.config/sentry. A non-absolute XDG_CONFIG_HOME is ignored per the spec.

Changes

• packages/cli/src/lib/db/index.ts — new exported resolveConfigDir(env, home) helper; getConfigDir() delegates to it.
• packages/cli/test/lib/config.test.ts — unit tests covering all four precedence branches plus the non-absolute XDG_CONFIG_HOME case.
• Docs updated: README.md, DEVELOPMENT.md, apps/cli-docs/src/fragments/configuration.md, apps/cli-docs/src/content/docs/getting-started.mdx.

Testing

vitest run test/lib/config.test.ts — 47 tests pass (5 new). Biome clean on changed files.

Note: binary install paths (~/.sentry/bin) are driven by the install script and left unchanged; this PR scopes to the config/data directory only.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	操作	Updated (UTC)
cli	Ready	Preview	Aug 28, 2026 6:04pm

[jared-outpost]

CI green on the feature branch (check_suite success). Self-review clean. Marking ready and requesting review from the issue author.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 2c52b8d. Configure here.}

[BYK]

Jared, we need to do the following:

1. Move the binary install path to either the new config directory or the appropriate directory based on the XDG Base Directory spec
2. We should migrate the config directory instead of leaving it at the old place. The best place for this is the setup command I think

[jared-outpost]

ack — will update binary install paths to follow XDG (via resolveConfigDir) and add migration logic inside setup so legacy ~/.sentry moves to the new location on first run. expanding scope as requested.

[BYK]

Jared, update the patch already?

[jared-outpost]

working on it — expanding to XDG-aware binary paths + migration inside setup. will push the update shortly.

[jared-outpost]

yep, expanding the patch now to also move binary install paths to XDG (via XDG_BIN_HOME / ~/.local/bin) and add migration inside setup. will push the update.

[jared-outpost]

expanding the patch now to cover XDG binary paths + migration in setup. pushing shortly.

[jared-outpost]

not yet — expanding determineInstallDir + setup migration for binary paths now. will push once the XDG-aware logic + migration is in.