Skip to content

CLI UX: cache invalidation, env var discoverability, and error message improvements #785

@BYK

Description

@BYK

Bundling a set of UX issues surfaced while testing the Sentry CLI against a freshly provisioned project (via Stripe Projects integration). Individually low-severity but collectively they make the CLI harder to use when the common "works out of the box" path doesn't apply.

Caching

  1. `-f/--fresh` flag is undocumented and non-discoverable. The flag exists on `org list`, `project view`, `auth whoami`, etc. but isn't mentioned in the top-level `sentry --help` or in the configuration docs. Users hit stale data with no indication that a refresh flag exists. Consider:

    • Adding a "Common flags" section to `sentry --help` that documents `-f`.
    • Emitting a subtle hint in list/view output when data came from cache (e.g. dim "cached · 5m old · use -f to refresh").
  2. Caches should auto-invalidate on known mutations. When the CLI itself performs an operation that changes state (`project delete`, `project create`, `issue resolve`, `issue unresolve`, `auth login`, `auth logout`), it should invalidate the corresponding cache entries automatically. Today users have to remember `-f` after mutations, which defeats the purpose of caching.

  3. `sentry auth whoami` returns a stale identity after switching accounts. Same family as refactor: use native Sentry device flow, remove oauth-proxy #2 — `auth login` / `auth logout` should invalidate the `whoami` cache.

Auth and environment variables

  1. `SENTRY_FORCE_ENV_TOKEN` is undiscoverable. Nothing in `sentry --help`, `sentry auth --help`, or https://cli.sentry.dev/configuration/ documents this. It's critical for the common case of "I have a valid token for a resource my logged-in user can't see." Suggested fix: when `SENTRY_AUTH_TOKEN` is set and there's a stored login, emit a hint:

    ```
    Detected SENTRY_AUTH_TOKEN env var but also a stored login for .
    Using stored login. To force the env var, set SENTRY_FORCE_ENV_TOKEN=1.
    ```

  2. Env var documentation is incomplete. https://cli.sentry.dev/configuration/ should list every env var the CLI honors (`SENTRY_AUTH_TOKEN`, `SENTRY_FORCE_ENV_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_DSN`, `SENTRY_URL`, `SENTRY_LOG_LEVEL`, `SENTRY_PLAIN_OUTPUT`, `NO_COLOR`, etc.). `gh` CLI does this under an "ENVIRONMENT VARIABLES" section in `gh --help` and in its docs; worth mirroring.

  3. `sentry --help` should have an "Environment Variables" section. Similar to how `gh --help` documents `GH_TOKEN`, `GH_HOST`, etc. at the top level. At minimum `SENTRY_AUTH_TOKEN` and `SENTRY_FORCE_ENV_TOKEN` deserve top-level visibility.

  4. OAuth-style provisioned tokens break `auth whoami -f`. Tokens issued by OAuth-style flows (e.g., Stripe Projects, Vercel integrations) don't support the `/auth/` endpoint and return 400 when `auth whoami -f` hits it. The CLI should either (a) detect OAuth-style tokens and skip the `/auth/` call, or (b) fall back to an endpoint that works (like `GET /users/me/` or similar).

Error messages

  1. `sentry project view /` says "Could not auto-detect organization and project" even when the user explicitly provided them. The real failure is usually "you lack access to that org/project" but the error tells the user to provide org/project, which they already did. Should distinguish "target not provided" from "target provided but inaccessible" and emit the actual API error in the latter case.

  2. Scope-related errors list generic scopes instead of the specific missing one. Running `sentry issue list` with a token missing `event:read` emits:
    ```
    You do not have permission to perform this action.
    Suggestions:
    • Your SENTRY_AUTH_TOKEN token may lack the required scopes (org:read, project:read)
    ```
    The token actually has `org:read` and `project:read`; the missing scope is `event:read`. The API response usually includes the specific scope — the CLI should surface that instead of a hardcoded generic list.

Output noise

  1. `New nightly available: ...` prints on every invocation. Clutters scripts, CI output, screen-sharing, and repeated commands. Should be rate-limited (once per day / session) or opt-in via a flag.

  2. `sentry api` prints a `WARN Endpoint includes the /api/0/ prefix` banner every time a user includes `/api/0/` in the endpoint. It's not actually a warning — it's a silent auto-fix. Should be DEBUG-level or just silently accept both forms without warning.

Context

These were observed while building and validating the Sentry ↔ Stripe Projects integration. The `SENTRY_FORCE_ENV_TOKEN` one was the most painful — spent ~30min figuring out why a valid provisioned token couldn't query its own resources before learning the env var exists.

Happy to split this into individual issues if that's preferred, or pick any of them up myself with guidance on the implementation approach.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions