no easy way to find or clear the cache, and `gargle_oauth_cache()` docs show wrong default path?

[MatthieuStigler]

It is very hard to find or clear the cache, partly because the gargle_oauth_cache() docs show wrong default path. So in this issue, I would like to :

1. Report a doc issue
2. Feature request: add

Documentation: gargle_oauth_cache() states wrong default path?

The documentation for gargle_oauth_cache() states:

TRUE means to cache using the default user-level cache file, ~/.R/gargle/gargle-oauth

But it seems that the default path is determined by rappdirs::user_cache_dir("gargle"), which resolves to ~/.cache/gargle on Linux (and platform-specific paths on macOS/Windows). Following the docs, a user would look in ~/.R/gargle/gargle-oauth, find nothing, and be stuck.

The actual tokens live in ~/.cache/gargle/, discoverable only by reading the source code or calling gargle::gargle_oauth_sitrep() (which is not referenced in ?gargle_oauth_cache).

Feature request: expose the cache path and provide a cache clearing helper

My use scenario: a cached token has stale or insufficient scopes, causing (403) Insufficient Permission errors. The fix is to delete the cached token and re-authenticate, but:

1. gargle_oauth_cache() returns TRUE, not a path
2. The documentation points to a path that does not exist
3. gargle_oauth_sitrep() shows the real path but is not cross-referenced from ?gargle_oauth_cache

It would help to have either:

1. A function like gargle_oauth_cache_path() that returns the cache path
2. A function like gargle_oauth_clear(email = "user@example.com") to delete a specific cached token
3. At minimum, updating the docs for gargle_oauth_cache() to show the correct default path and cross-reference gargle_oauth_sitrep()

Session info

• version: 1.6.1
• Platform: Linux (Ubuntu 24.04)