Create and load persistent GitHub authentication tokens for command-line apps
Last updated 10 months ago by rvagg .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ghauth 
SYNC missed versions from official npm registry.


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


Example usage

const ghauth = require('ghauth')
const authOptions = {
  // awesome.json within the user's config directory will store the token
  configName: 'awesome',

  // (optional) whatever GitHub auth scopes you require
  scopes: [ 'user' ],

  // (optional) saved with the token on GitHub
  note: 'This token is for my awesome app',

  // (optional)
  userAgent: 'My Awesome App'

const authData = await ghauth(authOptions)

// can also be run with a callback as:
// ghauth(authOptions, function (err, authData) {
//  console.log(authData)
// })

Will run something like this:

$ node awesome.js

GitHub username: rvagg
GitHub password: ✔✔✔✔✔✔✔✔✔✔✔✔
GitHub OTP (optional): 669684

{ user: 'rvagg',
  token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }

Because the token is persisted, the next time you run it there will be no prompts:

$ node awesome.js

{ user: 'rvagg',
  token: '24d5dee258c64aef38a66c0c5eca459c379901c2' }


ghauth(options, callback)

The options argument can have the following properties:

  • configName (String, required unless noSave is true): the name of the config you are creating, this is required for saving a <configName>.json file into the users config directory with the token created. Note that the config directory is determined by application-config and is OS-specific.
  • noSave (Boolean, optional): if you don't want to persist the token to disk, set this to true but be aware that you will still be creating a saved token on GitHub that will need cleaning up if you are not persisting the token.
  • authUrl (String, optional): defaults to for public GitHub but can be configured for private GitHub Enterprise endpoints.
  • promptName (String, optional): defaults to 'GitHub', change this if you are prompting for GHE credentials.
  • scopes (Array, optional): defaults to [], consult the GitHub scopes documentation to see what you may need for your application.
  • note (String, optional): defaults to 'Node.js command-line app with ghauth', override if you want to save a custom note with the GitHub token (user-visible).
  • userAgent (String, optional): defaults to 'Magic Node.js application that does magic things with ghauth', only used for requests to GitHub, override if you have a good reason to do so.
  • passwordReplaceChar (String, optional): defaults to '✔', the character echoed when the user inputs their password. Can be set to '' to silence the output.

The callback will be called with either an Error object describing what went wrong, or a data object as the second argument if the auth creation (or cache read) was successful. The shape of the second argument is { user:String, token:String }.


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 file for more details.

A note about tests

... there are no proper tests yet unfortunately. If you would like to contribute some that would be very helpful! We need to mock the GitHub API to properly test the functionality. Otherwise, testing of this library is done by its use downstream.


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

Rod Vagg GitHub/rvagg Twitter/@rvagg
Jeppe Nejsum Madsen GitHub/jeppenejsum Twitter/@nejsum
Max Ogden GitHub/maxogden Twitter/@maxogden

License & copyright

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 file for more details.

Current Tags

  • 4.0.0                                ...           latest (10 months ago)

16 Versions

  • 4.0.0                                ...           10 months ago
  • 3.2.1                                ...           4 years ago
  • 3.2.0                                ...           5 years ago
  • 3.1.0                                ...           5 years ago
  • 3.0.0                                ...           5 years ago
  • 2.0.1                                ...           5 years ago
  • 2.0.0                                ...           6 years ago
  • 1.0.0                                ...           6 years ago
  • 0.3.1                                ...           6 years ago
  • 0.3.0                                ...           6 years ago
  • 0.2.0                                ...           6 years ago
  • 0.1.1                                ...           6 years ago
  • 0.1.0                                ...           6 years ago
  • 0.0.2                                ...           6 years ago
  • 0.0.1                                ...           6 years ago
  • 0.0.0                                ...           7 years ago
Maintainers (1)
Today 8
This Week 77
This Month 192
Last Day 8
Last Week 108
Last Month 207
Dependencies (4)
Dev Dependencies (1)

Copyright 2014 - 2016 © |