From cbe4a68b5497da02cfd6e458c854aefe4dcbe22d Mon Sep 17 00:00:00 2001 From: betegon Date: Thu, 12 Mar 2026 18:19:42 +0100 Subject: [PATCH 1/6] docs: update credential storage docs and remove stale config.json references Auth credentials moved to SQLite (cli.db) but several docs pages and code comments still referenced the old ~/.sentry/config.json file. Rewrites the auth command docs with the actual schema, env var precedence, and external access instructions. Fixes stale comments in logout, oauth, and dsn types. Co-Authored-By: Claude Opus 4.6 --- docs/src/content/docs/commands/auth.md | 42 +++++++++++++++++++------- docs/src/content/docs/configuration.md | 4 ++- src/commands/auth/logout.ts | 2 +- src/lib/dsn/types.ts | 2 +- src/lib/oauth.ts | 2 +- 5 files changed, 37 insertions(+), 15 deletions(-) diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md index ac0ffc19a..12532b4a1 100644 --- a/docs/src/content/docs/commands/auth.md +++ b/docs/src/content/docs/commands/auth.md @@ -84,18 +84,38 @@ sentry auth refresh This is typically handled automatically when tokens expire. -## Configuration +## Credential Storage -Credentials are stored in `~/.sentry/config.json` with restricted file permissions (mode 600). +We store credentials in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600). The database uses a single-row `auth` table with the following columns: -**Config structure:** +| Column | Type | Description | +|--------|------|-------------| +| `token` | TEXT | OAuth access token | +| `refresh_token` | TEXT | OAuth refresh token | +| `expires_at` | INTEGER | Token expiry (ms since epoch) | +| `issued_at` | INTEGER | Token issue time (ms since epoch) | +| `updated_at` | INTEGER | Last modification time (ms since epoch) | -```json -{ - "auth": { - "token": "...", - "refreshToken": "...", - "expiresAt": "2024-12-31T00:00:00Z" - } -} +### Environment Variable Precedence + +The CLI checks for auth tokens in the following order, using the first one found: + +1. `SENTRY_AUTH_TOKEN` environment variable +2. `SENTRY_TOKEN` environment variable (legacy) +3. The `auth` table in the SQLite database + +When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh. + +### Reading the Token Externally + +Other tools can read the stored token directly from the database. The config directory defaults to `~/.sentry/` but can be overridden with the `SENTRY_CONFIG_DIR` environment variable. + +```bash +sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" ``` + +Keep in mind a few caveats when accessing the database from outside the CLI: + +- **Token expiry** — Check `expires_at` before using the token. The CLI automatically refreshes tokens when they are close to expiring, but an external reader will not trigger a refresh. +- **WAL mode** — The database uses SQLite WAL (Write-Ahead Logging). Open it in read-only mode to avoid lock contention with a running CLI process. +- **Env var precedence** — If `SENTRY_AUTH_TOKEN` or `SENTRY_TOKEN` is set, the CLI uses that instead of the database value. We recommend following the same precedence in external tools. diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md index 7e0efec24..23096080e 100644 --- a/docs/src/content/docs/configuration.md +++ b/docs/src/content/docs/configuration.md @@ -138,9 +138,11 @@ The `sentry api` command also uses `--verbose` to show full HTTP request/respons ## Credential Storage -Credentials are stored in a SQLite database at `~/.sentry/` (or the path set by `SENTRY_CONFIG_DIR`) with restricted file permissions (mode 600) for security. The database also caches: +We store credentials and caches in a SQLite database (`cli.db`) inside the config directory (`~/.sentry/` by default, overridable via `SENTRY_CONFIG_DIR`). The database file and its WAL side-files are created with restricted permissions (mode 600) so that only the current user can read them. The database also caches: - Organization and project defaults - DSN resolution results - Region URL mappings - Project aliases (for monorepo support) + +Other tools can query the database directly to read the stored auth token. See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for the schema and usage details. diff --git a/src/commands/auth/logout.ts b/src/commands/auth/logout.ts index 5565c3239..82b68e588 100644 --- a/src/commands/auth/logout.ts +++ b/src/commands/auth/logout.ts @@ -30,7 +30,7 @@ export const logoutCommand = buildCommand({ docs: { brief: "Log out of Sentry", fullDescription: - "Remove stored authentication credentials from the configuration file.", + "Remove stored authentication credentials from the local database.", }, output: { json: true, human: formatLogoutResult }, parameters: { diff --git a/src/lib/dsn/types.ts b/src/lib/dsn/types.ts index a0f5040da..200ad8555 100644 --- a/src/lib/dsn/types.ts +++ b/src/lib/dsn/types.ts @@ -66,7 +66,7 @@ export type ResolvedProject = ResolvedProjectInfo & { /** * Cached DSN entry with full resolution info * - * Stored in ~/.sentry/config.json under dsnCache[directory] + * Stored in ~/.sentry/cli.db in the dsn_cache table */ export type CachedDsnEntry = { /** The raw DSN string */ diff --git a/src/lib/oauth.ts b/src/lib/oauth.ts index 988fae206..c67701831 100644 --- a/src/lib/oauth.ts +++ b/src/lib/oauth.ts @@ -301,7 +301,7 @@ export async function performDeviceFlow( } /** - * Complete the OAuth flow by storing the token in the config file. + * Complete the OAuth flow by storing the token in the database. * * @param tokenResponse - The token response from performDeviceFlow */ From 4cc8fc81cb4fa8d5e19351042e5e8f34ecb60871 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 12 Mar 2026 17:20:21 +0000 Subject: [PATCH 2/6] chore: regenerate SKILL.md --- plugins/sentry-cli/skills/sentry-cli/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/plugins/sentry-cli/skills/sentry-cli/SKILL.md index 452150de4..fffe43cf0 100644 --- a/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -86,6 +86,8 @@ Refresh your authentication token ```bash sentry auth refresh + +sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" ``` #### `sentry auth status` From 86a7ca10c318f5c117b1379d3f2332f67377a499 Mon Sep 17 00:00:00 2001 From: betegon Date: Thu, 12 Mar 2026 18:38:50 +0100 Subject: [PATCH 3/6] docs: reframe credential storage docs for new users Rename "Reading the Token Externally" to "Direct Database Access" and broaden the framing to orient new users on inspecting stored data rather than just extracting a token. Add expires_at query example. Co-Authored-By: Claude Opus 4.6 --- docs/src/content/docs/commands/auth.md | 12 ++++++++---- docs/src/content/docs/configuration.md | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md index 12532b4a1..c58cf0e55 100644 --- a/docs/src/content/docs/commands/auth.md +++ b/docs/src/content/docs/commands/auth.md @@ -106,16 +106,20 @@ The CLI checks for auth tokens in the following order, using the first one found When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh. -### Reading the Token Externally +### Direct Database Access -Other tools can read the stored token directly from the database. The config directory defaults to `~/.sentry/` but can be overridden with the `SENTRY_CONFIG_DIR` environment variable. +If you need to inspect your stored credentials or integrate the CLI's auth with other tools, you can query the database directly. The config directory defaults to `~/.sentry/` but can be overridden with the `SENTRY_CONFIG_DIR` environment variable. ```bash +# Read the current access token sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" + +# Check token expiry +sqlite3 ~/.sentry/cli.db "SELECT datetime(expires_at / 1000, 'unixepoch') FROM auth WHERE id = 1;" ``` Keep in mind a few caveats when accessing the database from outside the CLI: -- **Token expiry** — Check `expires_at` before using the token. The CLI automatically refreshes tokens when they are close to expiring, but an external reader will not trigger a refresh. +- **Token expiry** — Check `expires_at` before using the token. The CLI automatically refreshes expired tokens, but reading the database directly will not trigger a refresh. - **WAL mode** — The database uses SQLite WAL (Write-Ahead Logging). Open it in read-only mode to avoid lock contention with a running CLI process. -- **Env var precedence** — If `SENTRY_AUTH_TOKEN` or `SENTRY_TOKEN` is set, the CLI uses that instead of the database value. We recommend following the same precedence in external tools. +- **Env var precedence** — If `SENTRY_AUTH_TOKEN` or `SENTRY_TOKEN` is set, the CLI ignores the database value. Follow the same precedence in external tools. diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md index 23096080e..6a905cd2a 100644 --- a/docs/src/content/docs/configuration.md +++ b/docs/src/content/docs/configuration.md @@ -145,4 +145,4 @@ We store credentials and caches in a SQLite database (`cli.db`) inside the confi - Region URL mappings - Project aliases (for monorepo support) -Other tools can query the database directly to read the stored auth token. See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for the schema and usage details. +Other tools can query the database directly to inspect stored credentials and cached data. See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for the full schema and access details. From dc99816805a1a68bc9a6a0ddb1a0ef8c8672c22d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 12 Mar 2026 17:39:25 +0000 Subject: [PATCH 4/6] chore: regenerate SKILL.md --- plugins/sentry-cli/skills/sentry-cli/SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/plugins/sentry-cli/skills/sentry-cli/SKILL.md index fffe43cf0..f0bdd1e00 100644 --- a/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -87,7 +87,11 @@ Refresh your authentication token ```bash sentry auth refresh +# Read the current access token sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" + +# Check token expiry +sqlite3 ~/.sentry/cli.db "SELECT datetime(expires_at / 1000, 'unixepoch') FROM auth WHERE id = 1;" ``` #### `sentry auth status` From a2545762a0f4b0ed0dae796874320ef96d75c947 Mon Sep 17 00:00:00 2001 From: betegon Date: Thu, 12 Mar 2026 20:40:04 +0100 Subject: [PATCH 5/6] docs: remove DB schema details and direct access examples Users should use `sentry auth token` and `sentry auth status` instead of querying the database directly. Remove the auth table schema, sqlite3 examples, and direct database access encouragement. Co-Authored-By: Claude Opus 4.6 --- docs/src/content/docs/commands/auth.md | 30 ++----------------- docs/src/content/docs/configuration.md | 2 +- plugins/sentry-cli/skills/sentry-cli/SKILL.md | 6 ---- 3 files changed, 4 insertions(+), 34 deletions(-) diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md index c58cf0e55..9038f63da 100644 --- a/docs/src/content/docs/commands/auth.md +++ b/docs/src/content/docs/commands/auth.md @@ -86,15 +86,9 @@ This is typically handled automatically when tokens expire. ## Credential Storage -We store credentials in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600). The database uses a single-row `auth` table with the following columns: +Credentials are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600). -| Column | Type | Description | -|--------|------|-------------| -| `token` | TEXT | OAuth access token | -| `refresh_token` | TEXT | OAuth refresh token | -| `expires_at` | INTEGER | Token expiry (ms since epoch) | -| `issued_at` | INTEGER | Token issue time (ms since epoch) | -| `updated_at` | INTEGER | Last modification time (ms since epoch) | +Use `sentry auth token` to retrieve your current access token, or `sentry auth status` to check authentication state. ### Environment Variable Precedence @@ -102,24 +96,6 @@ The CLI checks for auth tokens in the following order, using the first one found 1. `SENTRY_AUTH_TOKEN` environment variable 2. `SENTRY_TOKEN` environment variable (legacy) -3. The `auth` table in the SQLite database +3. The stored token in the SQLite database When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh. - -### Direct Database Access - -If you need to inspect your stored credentials or integrate the CLI's auth with other tools, you can query the database directly. The config directory defaults to `~/.sentry/` but can be overridden with the `SENTRY_CONFIG_DIR` environment variable. - -```bash -# Read the current access token -sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" - -# Check token expiry -sqlite3 ~/.sentry/cli.db "SELECT datetime(expires_at / 1000, 'unixepoch') FROM auth WHERE id = 1;" -``` - -Keep in mind a few caveats when accessing the database from outside the CLI: - -- **Token expiry** — Check `expires_at` before using the token. The CLI automatically refreshes expired tokens, but reading the database directly will not trigger a refresh. -- **WAL mode** — The database uses SQLite WAL (Write-Ahead Logging). Open it in read-only mode to avoid lock contention with a running CLI process. -- **Env var precedence** — If `SENTRY_AUTH_TOKEN` or `SENTRY_TOKEN` is set, the CLI ignores the database value. Follow the same precedence in external tools. diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md index 6a905cd2a..49e986232 100644 --- a/docs/src/content/docs/configuration.md +++ b/docs/src/content/docs/configuration.md @@ -145,4 +145,4 @@ We store credentials and caches in a SQLite database (`cli.db`) inside the confi - Region URL mappings - Project aliases (for monorepo support) -Other tools can query the database directly to inspect stored credentials and cached data. See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for the full schema and access details. +See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for more details. diff --git a/plugins/sentry-cli/skills/sentry-cli/SKILL.md b/plugins/sentry-cli/skills/sentry-cli/SKILL.md index f0bdd1e00..452150de4 100644 --- a/plugins/sentry-cli/skills/sentry-cli/SKILL.md +++ b/plugins/sentry-cli/skills/sentry-cli/SKILL.md @@ -86,12 +86,6 @@ Refresh your authentication token ```bash sentry auth refresh - -# Read the current access token -sqlite3 ~/.sentry/cli.db "SELECT token FROM auth WHERE id = 1;" - -# Check token expiry -sqlite3 ~/.sentry/cli.db "SELECT datetime(expires_at / 1000, 'unixepoch') FROM auth WHERE id = 1;" ``` #### `sentry auth status` From 40bee0773ebd4f95b076cf5a0a0b4ad7d5d0e584 Mon Sep 17 00:00:00 2001 From: betegon Date: Fri, 13 Mar 2026 10:12:52 +0100 Subject: [PATCH 6/6] docs: fix "(legacy)" label on env var precedence SENTRY_TOKEN is the new env var (inspired by GITHUB_TOKEN), while SENTRY_AUTH_TOKEN is the legacy one. The label was on the wrong variable. Co-Authored-By: Claude Opus 4.6 --- docs/src/content/docs/commands/auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md index 9038f63da..4354d768f 100644 --- a/docs/src/content/docs/commands/auth.md +++ b/docs/src/content/docs/commands/auth.md @@ -94,8 +94,8 @@ Use `sentry auth token` to retrieve your current access token, or `sentry auth s The CLI checks for auth tokens in the following order, using the first one found: -1. `SENTRY_AUTH_TOKEN` environment variable -2. `SENTRY_TOKEN` environment variable (legacy) +1. `SENTRY_AUTH_TOKEN` environment variable (legacy) +2. `SENTRY_TOKEN` environment variable 3. The stored token in the SQLite database When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.