Helper utility for cli authentication flow with GitHub

Usage no npm install needed!

<script type="module">
  import ahmadnassriGithubCliAuth from 'https://cdn.skypack.dev/@ahmadnassri/github-cli-auth';


GitHub Auth CLI Helper

License version Build Status

Helper utility for cli authentication flow with GitHub

Creates and manages Personal Access Tokens, prompting the user for username, password, 2FA as needed, while using the system's keychain to store secrets.


npm install @ahmadnassri/github-cli-auth

OS Support

OS Secret Manager Setup Needed
macOS Keychain
Windows Credential Vault
Linux Secret Service API Draft / libsecret

Linux Setup: Install libsecret before running npm install:

  • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
  • Red Hat-based: sudo yum install libsecret-devel
  • Arch Linux: sudo pacman -S libsecret

CLI Flag

passing --no-store in the CLI of parent app, will automatically skip using the keychain


Method : _(namespace)

creates a new namespace in the system's keychain, returns an Object with two methods: token & reset

name type required default description
namespace String - namespace value to use in keychain
const auth = require('@ahmadnassri/github-cli-auth')

const { token, reset } = auth('my-awesome-app')

Method : token([options])

creates a personal access token for supplied scopes, prompts for username, password & 2FA as needed.


name type required default description
remember Object { lastuser: true, password: false } store additional info
scopes Array ['repo'] scopes to authenticate
const auth = require('@ahmadnassri/github-cli-auth')

const { token } = auth('my-awesome-app')

token({ scopes: ['admin:org', 'repo'] }).then(console.log) 
//=> { username: 'ahmadnassri', token: '88688d7a17c52e893e6dc27a2d22734955740c04' }

Method : reset(username)

delete stored secrets for a given username

name type required default description
username String - username to erase
const auth = require('@ahmadnassri/github-cli-auth')

const { reset } = auth('my-awesome-app')

reset('ahmadnassri') // deletes stored secrets for 'ahmadnassri'


Set NODE_DEBUG=GITHUB_AUTH for additional debug logs

Author: Ahmad Nassri • Github: @ahmadnassri • Twitter: @AhmadNassri