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.jsPersonal 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 tokenPaste your token here: ✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔✔ Authorized for rvaggWrote access token to "/home/rvagg/.config/my-app/config.json"{ user: 'rvagg', token: 'ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' }
API
ghauth(options)
Returns a Promise that resolves to { user: String, token: String }.
Options
Option
Type
Required
Description
configName
String
Yes*
Name for the config file. Creates <configName>/config.json in the user's config directory. *Not required if noSave: true.
scopes
Array
No
GitHub API scopes your app requires. Defaults to [].
noSave
Boolean
No
Don't persist the token to disk.
clientId
String
No
Token formats
ghauth accepts all GitHub PAT formats:
Classic PATs: 40 hex characters or ghp_ prefix
Fine-grained PATs: github_pat_ prefix
OAuth Device Flow
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.
// Before (v6)const ghauth = require('ghauth')// After (v7)import ghauth from 'ghauth'
Promise-only API - Callbacks removed:
// Before (v6)ghauth(options, (err, data) => { ... })// After (v7)const data = await ghauth(options)
Node.js 20+ required
PAT flow is now the default - No need for noDeviceFlow: true or clientId. Just provide configName and optional scopes.
PAT validation updated - Now accepts fine-grained PATs ( prefix) in addition to classic PATs.
Contributing
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.
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.