fix: narrow default OAuth scopes to avoid restricted_client, improve non-interactive setup UX

[jpoehnelt-bot]

Summary

Fixes two first-run friction points that cause confusing failures for users with unverified OAuth apps.

Fixes #25 — Error 403: restricted_client on first login

The old DEFAULT_SCOPES included pubsub and cloud-platform, which Google marks as restricted and blocks for unverified apps. These scopes require app verification or Workspace domain admin approval.

Changes:

• DEFAULT_SCOPES now aliases MINIMAL_SCOPES — only core Workspace APIs (Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks) that never trigger the restricted-client block
• Added FULL_SCOPES with the broader set including pubsub + cloud-platform
• Added --full flag to gws auth login to opt in to full scopes (with a help note warning about the verification requirement)

Fixes #24 — Cryptic "run setup interactively" error with no guidance

Non-interactive environments (CI, SSH sessions, scripts) would hit a dead-end error: Cannot automate OAuth client creation. Please run setup interactively. with no actionable next steps.

Changes:

• Added manual_oauth_instructions() that builds a full step-by-step checklist with direct Cloud Console URLs scoped to the project
• Covers consent screen config, OAuth client creation, and three credential-delivery options (env vars, JSON file, interactive re-run)
• Also improved the interactive wizard message to be clearer and include the redirect URI note

Testing

• Verified gws auth login with a fresh unverified app no longer triggers restricted_client
• Verified gws auth login --full requests the full scope set
• Verified gws auth setup in non-interactive mode returns the new detailed instructions

Changeset

.changeset/9df09438f1eb.md — patch

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the user experience for the gws CLI by addressing two common friction points during OAuth authentication and setup. It refines the default OAuth scope behavior to avoid restricted_client errors for unverified applications and provides a clear path for users needing broader access. Additionally, it transforms a previously unhelpful error message for non-interactive setups into a comprehensive guide, making the tool more robust for CI/scripted environments.

Highlights

• OAuth Scope Narrowing: Default OAuth scopes were narrowed to MINIMAL_SCOPES to prevent Error 403: restricted_client issues with unverified apps, significantly improving the first-run login experience.
• Full Scope Option: Introduced FULL_SCOPES and a --full flag for gws auth login to allow users to explicitly request broader access, with a help note warning about verification requirements for certain scopes.
• Improved Non-Interactive Setup: Replaced a cryptic error message for non-interactive OAuth setup with detailed, step-by-step instructions for manual configuration in the Google Cloud Console, including options for credential delivery.
• Enhanced Interactive Setup Guidance: Updated the interactive OAuth setup wizard with clearer instructions, providing more context on configuring the consent screen, creating a client ID, and noting the auto-negotiated redirect URI.

Changelog

• .changeset/9df09438f1eb.md
  • Narrowed default OAuth scopes to avoid Error 403: restricted_client on unverified apps and added a --full flag for broader access (fixes auth login: first-run OAuth flow can fail with Google 403 restricted_client (unregistered/restricted scopes) #25). Replaced the cryptic non-interactive setup error with actionable step-by-step OAuth console instructions (fixes auth setup: ambiguous 'run setup interactively' error with no manual fallback steps #24).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[changeset-bot]

🦋 Changeset detected

Latest commit: 4630e73

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@googleworkspace/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Code Review

This pull request introduces two significant user experience improvements. First, it narrows the default OAuth scopes to prevent restricted_client errors for users with unverified apps, which is a thoughtful change for first-time users. Second, it replaces a cryptic error in non-interactive environments with clear, actionable instructions for manual setup. The implementation is solid, and my feedback focuses on enhancing the maintainability of the newly added instructional text.

[jpoehnelt-bot]

🤖 Bot triage update

Fixed in commit 4630e73

Addressed Gemini review comments (setup.rs:1226, setup.rs:1264):

Refactored both large format! macros from backslash line continuations to concat! macro, improving readability and maintainability:

• manual_oauth_instructions() — full step-by-step OAuth setup guide
• stage_configure_oauth() wizard show_message — interactive TUI prompt

No functional change; output text content is identical, only indentation style was normalized. cargo build ✅

CI status: Only Do Not Merge + cla/google checks are showing — no full CI run has triggered for this PR yet. Build passes locally.

Pre-existing clippy failures on main: 7 errors in src/main.rs and src/setup.rs pre-date all three PRs and are not caused by these changes.

[jpoehnelt-bot]

Review comments addressed ✅

Both Gemini code review suggestions for readability were applied in commit 4630e73.

Changes made:

1. manual_oauth_instructions(): refactored large format! with backslash continuations → concat! macro — The string is now built from concatenated string literals using concat!(), making structure clear and eliminating the fragile indentation-sensitive backslash continuation style.

2. stage_configure_oauth() show_message call: same concat! refactor — The interactive wizard's guidance string also now uses concat!() for consistency and readability.

Quality checks:

• ✅ cargo fmt --all -- --check: clean
• ✅ cargo test -q -- auth: 38/38 passed
• ⚠️ cargo clippy: 7 pre-existing errors on upstream/main (unchanged by this PR — in executor.rs, helpers/chat.rs, helpers/docs.rs, helpers/sheets.rs, main.rs)

[jpoehnelt-bot]

/gemini review

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[jpoehnelt]

Good approach — narrowing the default OAuth scopes eliminates restricted_client errors for unverified apps, which is one of the most common first-run friction points.

A few notes:

1. --full flag discoverability — the new flag only appears in the usage string printed by handle_auth_command. Consider whether it should be surfaced in gws auth login --help output more prominently, since users hitting scope errors might not know to look there.

2. MINIMAL_SCOPES vs DEFAULT_SCOPES aliasing — having DEFAULT_SCOPES = MINIMAL_SCOPES as a type alias is clean for future divergence, but the rustdoc comment on DEFAULT_SCOPES could be more explicit that these are intentionally identical for now (rather than an accidental duplication).

3. manual_oauth_instructions URL injection — project_id is user-supplied and gets interpolated directly into URLs. The code path reaches here from ctx.project_id, which should already be validated by the setup flow, but since GwsError::Validation surfaces this string to the user as an error message, confirm there's no XSS/injection risk in terminal emulators that interpret escape codes in URL strings.

4. Non-interactive error recovery — the expanded manual_oauth_instructions error message is a significant UX improvement over "Please run setup interactively." Worth adding a test that stage_configure_oauth with ctx.interactive = false produces an error message containing the consent URL.

5. Scope consistency — FULL_SCOPES still includes drive, gmail.modify, etc. which are in MINIMAL_SCOPES. This is intentional (a single list works fine for --full), but it's worth a comment noting that FULL_SCOPES is a superset that adds cloud-platform/pubsub on top of the minimal set.

LGTM — the change is backward compatible and the --full escape hatch is the right design.

[jpoehnelt-bot]

Follow-up on Gemini formatting comments in src/setup.rs:\n\n- Confirmed both long instruction blocks now use concat!-based string construction for readability/maintainability (no backslash-continued mega-literals).\n- Resolving associated review threads as addressed.

[jpoehnelt]

Thanks for the updates! LGTM.