From 7cf4e05263419e118f6971b22326dd2a29550bf5 Mon Sep 17 00:00:00 2001 From: Rian Stockbower Date: Tue, 27 Jan 2026 07:09:01 -0500 Subject: [PATCH] docs: add guidance about OAuth app publishing status Add documentation to help users understand they should publish their OAuth app to avoid 7-day token expiration: - README: New setup step explaining Testing vs Production mode - README: Troubleshooting entry for token expiration - init command: Tip after successful auth about publishing - init command: Note in credentials setup instructions Apps in "Testing" mode have refresh tokens that expire after 7 days, forcing frequent re-authentication. Publishing the app (which is straightforward for personal use with read-only scopes) extends token lifetime to 6 months of inactivity. Closes #90 Co-Authored-By: Claude Opus 4.5 --- README.md | 20 ++++++++++++++++++-- internal/cmd/initcmd/init.go | 6 ++++++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cdf04b0..5b4fb6d 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,19 @@ go install github.com/open-cli-collective/google-readonly/cmd/gro@latest 5. Click **Create** 6. Download the JSON file -### 3. Configure gro +### 3. Publish Your OAuth App (Recommended) + +By default, new OAuth apps are in **"Testing"** mode, which causes **tokens to expire after 7 days**. To avoid frequent re-authentication: + +1. Go to **Google Auth Platform** > **Audience** (or **OAuth consent screen** in older UI) +2. Find the **Publishing status** section +3. Click **Publish app** + +For personal use with read-only scopes, publishing is straightforward and doesn't require Google verification. Once published, tokens will last until revoked or unused for 6 months. + +> **Note:** If you skip this step, you'll need to run `gro init` every 7 days to re-authenticate. + +### 4. Configure gro 1. Create the config directory: ```bash @@ -133,7 +145,7 @@ go install github.com/open-cli-collective/google-readonly/cmd/gro@latest mv ~/Downloads/client_secret_*.json ~/.config/google-readonly/credentials.json ``` -### 4. Authenticate +### 5. Authenticate Run the init command to complete OAuth setup: @@ -837,6 +849,10 @@ gro config clear gro init ``` +### Token expires every 7 days + +Your OAuth app is likely still in **"Testing"** mode. See [Publish Your OAuth App](#3-publish-your-oauth-app-recommended) in the setup guide. Apps in testing mode have tokens that expire after 7 days. + ## License MIT License - see [LICENSE](LICENSE) for details. diff --git a/internal/cmd/initcmd/init.go b/internal/cmd/initcmd/init.go index cc3d668..d05524e 100644 --- a/internal/cmd/initcmd/init.go +++ b/internal/cmd/initcmd/init.go @@ -211,6 +211,9 @@ func verifyConnectivity() error { fmt.Printf("Authenticated as: %s\n", profile.EmailAddress) fmt.Println() fmt.Println("Setup complete! Try: gro mail search \"is:unread\"") + fmt.Println() + fmt.Println("Tip: If your token expires every 7 days, your OAuth app may be in 'Testing' mode.") + fmt.Println(" Publish it at: Google Cloud Console > OAuth consent screen > Publish app") return nil } @@ -229,6 +232,9 @@ func printCredentialsInstructions(credPath string) { fmt.Println(" - Download the JSON file") fmt.Printf("5. Save the downloaded file to:\n %s\n", credPath) fmt.Println() + fmt.Println("Optional but recommended: Publish your OAuth app to avoid 7-day token expiry:") + fmt.Println(" - Go to 'OAuth consent screen' > 'Publish app'") + fmt.Println() fmt.Println("Then run 'gro init' again.") }