When building a CLI tool that needs GitHub access, you have three options:
- Ask users to create a personal access token manually (bad UX)
- Redirect to a web page (requires a server)
- Use the OAuth device flow
The device flow is what the GitHub CLI itself uses. Users run one command, a URL and code appear, they open it in any browser. No server, no copy-pasting tokens. Here's how to implement it cleanly.
The flow in three steps
1. POST /login/device/code
→ returns: device_code, user_code, verification_uri, expires_in, interval
2. Show the user:
"Open https://github.com/login/device/activate and enter: XXXX-YYYY"
3. Poll POST /login/oauth/access_token every {interval} seconds
→ returns: access_token (when user completes) or error codes (keep polling)
The implementation is ~100 lines. Most of the complexity is in handling the polling responses correctly.
Polling response codes
This is the part most tutorials skip. The responses aren't HTTP errors — they come back as 200 OK with an error field:
type PollResponse =
| { access_token: string; token_type: string }
| { error: 'authorization_pending' } // user hasn't authorized yet — keep polling
| { error: 'slow_down'; interval: number } // increase interval by 5s
| { error: 'expired_token' } // time's up — restart the flow
| { error: 'access_denied' } // user denied — stop
Treating all of these as errors breaks the UX. authorization_pending just means "not yet" — keep the spinner going.
The polling loop
async function pollForToken(deviceCode: string, intervalSecs: number): Promise<string> {
let interval = intervalSecs;
while (true) {
await sleep(interval * 1000);
const response = await fetch('https://github.com/login/oauth/access_token', {
method: 'POST',
headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({
client_id: CLIENT_ID,
device_code: deviceCode,
grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
}),
});
const data = await response.json();
if ('access_token' in data) return data.access_token;
if (data.error === 'slow_down') interval += 5;
if (data.error === 'expired_token') throw new Error('Authorization timed out. Run auth login again.');
if (data.error === 'access_denied') throw new Error('Authorization denied.');
// authorization_pending: continue loop
}
}
Token storage
Write to ~/.toolname/config.json and immediately chmod:
import { writeFileSync, chmodSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';
const configPath = join(homedir(), '.releasehub', 'config.json');
writeFileSync(configPath, JSON.stringify({ githubToken: token }), 'utf-8');
chmodSync(configPath, 0o600); // owner read/write only
Most CLIs skip the chmod and leave the token world-readable. Don't.
The full implementation is in ReleaseHub — a CLI for generating release notes from GitHub PRs. The auth module is standalone if you want to adapt it.