--auth default is documented as adc but defaults to oauth2 — and the ADC recommendation should stay

[crichalchemist]

Two related but separate things in the auth docs, posting here per CONTRIBUTING.md.

1. The documented default is wrong

src/colab_cli/cli.py:78 sets the flag default:

] = AuthProvider.OAUTH2,

and the installed CLI agrees — from colab --help on 0.6.0 (PyPI latest):

--auth  <oauth2|adc>  Authentication strategy to use: 'oauth2' (public
                      InstalledAppFlow), or 'adc' (Application Default
                      Credentials).
                      [default: oauth2]

Two docs state the opposite:

• README.md:108 — "--auth {oauth2,adc} — Authentication strategy for the Colab API (default: adc)."
• skills/colab-operator/SKILL.md:29 — "The global flag is --auth={adc,oauth2} and the default is adc (Application Default Credentials)."

SKILL.md is the bundled agent skill shipped through colab skill, so this one has teeth: an agent that reads it will omit --auth=adc believing it is redundant and silently take the oauth2 path instead. That is the opposite of what the same document recommends two paragraphs later.

2. The recommendation to prefer ADC should stay — #116 is the reason

Flagging this because the obvious correction — rewrite the docs so oauth2 reads as the primary path, since it is the default — would point agents at the path that is currently broken for a supported user choice.

Per #116, if a user approves only some of the six requested scopes on Google's granular consent screen:

• the login is discarded even though the code exchange returns 200, and ~/.config/colab-cli/token.json is never written;
• once past that, every refresh fails with invalid_scope and falls back to a fresh browser consent, in practice about hourly.

ADC does not have this problem: google/auth/_default.py loads credentials without forcing a scope list, whereas auth.py calls Credentials.from_authorized_user_file(TOKEN_CONFIG_PATH, PUBLIC_SCOPES) with an explicit one, and from_authorized_user_info only honors the scopes stored in the file when the caller passes None.

I hit this directly on macOS with 0.6.0: oauth2 did not work until I deleted the cached credentials and switched to --auth=adc, which has been stable since.

So the two statements that belong in the docs are different from each other:

• factual: the default is oauth2
• guidance: prefer --auth=adc, especially for unattended and agent use, while [Bug]: Partial (granular) consent breaks login and then forces a browser re-login every hour on --auth=oauth2 #116 is open

Today the docs get the first one wrong and the second one right, and it would be easy to "fix" them into getting the first right and the second wrong.

Prior art

#68 reported the same doc drift and #69 fixed it; both were closed on 2026-06-18 as NOT_PLANNED, directing external feedback here — hence this post rather than a patch.

Worth noting that this is not quite a re-run of #69. That PR, as written, would have updated SKILL.md to describe the OAuth2 remote copy-paste flow as the primary flow with "ADC as an explicit option." Given #116, that is the opposite of the guidance that seems right now.

No patch proposed — flagging per the contribution guidelines. Happy to supply the exact wording for either file if that is useful.