Create and load persistent GitHub authentication tokens for command-line apps

import ghauth from 'ghauth'

const authData = await ghauth({
  configName: 'my-app',
  scopes: ['repo']
})

console.log(authData)
// { user: 'rvagg', token: 'ghp_...' }

On first run, this prompts the user to create a Personal Access Token. The token is saved to ~/.config/my-app/config.json (Linux), ~/Library/Application Support/my-app/config.json (macOS), or %APPDATA%/my-app/config.json (Windows). Subsequent runs return the cached token without prompting.

$ node my-app.js
Personal access token auth for Github.

  Create a Personal Access Token at https://github.com/settings/tokens

    1. Click "Generate new token" → "Generate new token (classic)"
       (fine-grained tokens also work)
    2. Set a name, e.g. "my-app"
    3. Select scopes: repo
    4. Generate and copy the token

Paste your token here: ✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔
✔ Authorized for rvagg
Wrote access token to "/home/rvagg/.config/my-app/config.json"
{ user: 'rvagg', token: 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' }

ghauth(options)

Returns a Promise that resolves to { user: String, token: String }.

ghauth accepts all GitHub PAT formats:

• Classic PATs: 40 hex characters or ghp_ prefix
• Fine-grained PATs: github_pat_ prefix

If you register an OAuth App with GitHub, you can use the device flow instead of asking users to create PATs manually. This provides a smoother UX where users authorize in their browser.

const authData = await ghauth({
  clientId: 'your-oauth-app-client-id',
  configName: 'my-app',
  scopes: ['repo']
})

To set up an OAuth App:

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set any URL for the callback (it's not used by device flow)
4. Enable "Device Authorization Flow" in the app settings
5. Use the Client ID (not the secret) in your code

See GitHub's device flow documentation for details.

For GitHub Enterprise instances that use basic auth:

const authData = await ghauth({
  configName: 'my-app',
  authUrl: 'https://github.mycompany.com/api/v3/authorizations',
  scopes: ['repo']
})

Breaking Changes:

1. ESM only - Update imports:

   // Before (v6)
   const ghauth = require('ghauth')
   
   // After (v7)
   import ghauth from 'ghauth'

2. Promise-only API - Callbacks removed:

   // Before (v6)
   ghauth(options, (err, data) => { ... })
   
   // After (v7)
   const data = await ghauth(options)

3. Node.js 20+ required

4. PAT flow is now the default - No need for noDeviceFlow: true or clientId. Just provide configName and optional scopes.

5. PAT validation updated - Now accepts fine-grained PATs (github_pat_ prefix) in addition to classic PATs.

ghauth is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

ghauth is made possible by the excellent work of the following contributors:

Copyright (c) 2014 ghauth contributors (listed above).

ghauth is licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.