gluegun

A delightful toolkit for building Node-powered CLIs.

Usage no npm install needed!

<script type="module">
  import gluegun from 'https://cdn.skypack.dev/gluegun';
</script>

README

npm module CircleCI code style: prettier

Gluegun

gluegun

Gluegun is a delightful toolkit for building Node-based command-line interfaces (CLIs) in TypeScript or modern JavaScript, with support for:

🌯 parameters - command-line arguments and options
🎛 template - generating files from templates
🗄 patching - manipulating file contents
💾 filesystem - moving files and directories around
system - executing other command-line scripts
🎅 http - interacting with API servers
🛎 prompt - auto-complete prompts
💃 print - printing pretty colors and tables
👩‍✈️ semver - working with semantic versioning
🎻 strings - manipulating strings & template data
📦 packageManager - installing NPM packages with Yarn or NPM

In addition, gluegun supports expanding your CLI's ecosystem with a robust set of easy-to-write plugins and extensions.

Why use Gluegun?

You might want to use Gluegun if:

  • You need to build a CLI app
  • You want to have powerful tools at your fingertips
  • And you don't want to give up flexibility at the same time

If so ... welcome!

Quick Start

Just run the gluegun CLI like this:

# spin up your new CLI
npx gluegun new movies

# choose TypeScript or Modern JavaScript
# now jump into the source
cd movies

# and link your new executable
yarn link

# and run it!
movies help

You should see your new CLI help. Open the folder in your favorite editor and start building your CLI!

Code

Let's start with what a gluegun CLI looks like.

// in movie/src/cli.[js|ts]...

// ready
const { build } = require('gluegun')

// aim
const movieCLI = build('movie')
  .src(`${__dirname}/src`)
  .plugins('node_modules', { matching: 'movie-*' })
  .help()
  .version()
  .defaultCommand()
  .create()

// fire!
movieCLI.run()

Commands

Commands are simple objects that provide a name, optional aliases, and a function to run.

// in movie/src/commands/foo.js
module.exports = {
  name: 'foo',
  alias: 'f',
  run: async function (toolbox) {
    // gluegun provides all these features and more!
    const { system, print, filesystem, strings } = toolbox

    // ...and be the CLI you wish to see in the world
    const awesome = strings.trim(await system.run('whoami'))
    const moreAwesome = strings.kebabCase(`${awesome} and a keyboard`)
    const contents = `🚨 Warning! ${moreAwesome} coming thru! 🚨`
    const home = process.env['HOME']
    filesystem.write(`${home}/realtalk.json`, { contents })

    print.info(`${print.checkmark} Citius`)
    print.warning(`${print.checkmark} Altius`)
    print.success(`${print.checkmark} Fortius`)
  },
}

See the toolbox api docs for more details on what you can do.

See the runtime docs for more details on building your own CLI and join us in the #gluegun channel of the Infinite Red Community Slack (community.infinite.red) to get friendly help!

Who Is Using This?

Additionally, the first versions of the AWS Amplify CLI (a CLI toolchain for simplifying serverless web and mobile development) used Gluegun. They've since integrated Gluegun's functionality into their CLI in a bespoke way, but you can still see Gluegun patterns in their CLI.

What's under the hood?

We've assembled an all-star cast of libraries to help you build your CLI.

⭐️ ejs for templating
⭐️ semver for version investigations
⭐️ fs-jetpack for the filesystem
⭐️ yargs-parser, enquirer, colors, ora and cli-table3 for the command line
⭐️ axios & apisauce for web & apis
⭐️ cosmiconfig for flexible configuration
⭐️ cross-spawn for running sub-commands
⭐️ execa for running more sub-commands
⭐️ node-which for finding executables
⭐️ pluralize for manipulating strings

Node.js 12.0+ is required.

Community CLIs and Plugins

Here are a few community CLIs based on Gluegun plus some plugins you can use. Is yours missing? Send a PR to add it!

Sponsors

Gluegun is sponsored by Infinite Red, a premium custom mobile app and web design and development agency. We are a team of designers and developers distributed across the USA and based near Portland, Oregon. Our specialties are UI/UX design, React and React Native, Node, and more. Email hello@infinite.red if you'd like to talk about your project!