match-official-cli-oauth

Port OAuth flows from official CLIs byte-for-byte into a coding-agent harness.

10|1|Updated Jul 7, 2026
One-click install
npx skills add https://github.com/catalystctl/catcode --skill match-official-cli-oauth-catalystctl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: match-official-cli-oauth
Source: https://github.com/catalystctl/catcode/tree/main/.catalyst-code/skills/match-official-cli-oauth
Command: npx skills add https://github.com/catalystctl/catcode --skill match-official-cli-oauth-catalystctl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Reimplementing a provider's OAuth flow from scratch often produces subtle mismatches—wrong client IDs, missing scopes, incorrect endpoints, or incompatible token storage—that break token interchange with the official CLI. This Skill guides porting the reference CLI's OAuth implementation exactly, so tokens obtained by either tool work in both. ## Core Features & Use Cases - Exact constant extraction: Locates the reference CLI's auth source (e.g., gemini-cli's oauth2.ts) and copies client_id, scopes, endpoints, redirect URIs, PKCE behavior, and state format verbatim with file-and-line citations. - Token storage interchange: Mirrors the on-disk credential JSON shape (e.g., ~/.gemini/oauth_creds.json with millisecond expiry_date) so tokens are readable and writable by both tools. - Headless and SSH support: Implements the manual-code no-browser flow with suspend/resume state, OSC 52 clipboard copy, and rune-wrapped URL display for remote terminals. - Use Case: When asked to "make our Gemini OAuth match gemini-cli," the Skill walks through extracting the exact client ID, three scopes, v1 auth endpoint, and token exchange fields, then guards them with a constants test. ## Quick Start Make our provider OAuth flow match exactly how the official CLI does it, including constants, token storage format, and the headless login flow.

Frequently Asked Questions about match-official-cli-oauth

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make my app's OAuth match an official CLI exactly?

Locate the reference CLI's auth source code and copy the exact client_id, scopes, endpoints, redirect URI, and PKCE behavior rather than guessing constants. Then mirror its on-disk token JSON format so credentials are interchangeable, and add a test asserting the raw constant strings.

How do I find the OAuth client ID inside a CLI like gemini-cli?

Search the CLI's repository using the GitHub contents API and recursive tree, grepping for oauth, credential, login, and client_id. For gemini-cli the logic lives in packages/core/src/code_assist/oauth2.ts plus google-auth-library internals.

Why does Google OAuth fail with response_type missing error?

The v2 GIS endpoint (oauth2/v2/auth) drops installed-app auth-code query params on its internal redirect, causing Error 400 invalid_request. Use the v1 endpoint accounts.google.com/o/oauth2/auth that google-auth-library's generateAuthUrl defaults to.

How do I implement OAuth login over SSH without a browser?

Port the CLI's manual-code flow that displays the code on an OOB page, auto-selected when SSH_CONNECTION is set or DISPLAY is empty. Suspend the flow by stashing the PKCE verifier in state and resume via a separate command, and copy the long authorize URL to the local clipboard using OSC 52.

Should state be included in the OAuth token exchange body?

No. Per RFC 6749, state belongs only in the authorize URL. Sending it in the token exchange can cause the endpoint to reject the request and burn the single-use authorization code, making all retries fail with invalid_grant.

Why does token expiry differ between my app and the reference CLI?

google-auth-library stores expiry_date in milliseconds while many implementations use seconds. Convert between milliseconds and seconds at the read/write boundary and unit-test the round-trip to keep stored credentials compatible.