Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

helpful-cli

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

helpful-cli

Command line utility for custom project scaffolding.

  • 2.0.0-alpha
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
0
decreased by-100%
Maintainers
1
Weekly downloads
 
Created
Source

Helpful CLI

tl; dr "Templatize Anything"

This tool is currently undergoing a massive rewrite. You can still use the original version of this tool by installing it via npm, or review its source on the v1 branch.

Helpful CLI is a command line utility for quickly scaffolding new projects, or add files to existing projects, using remote templates. It's kind of like a Makefile, but on steroids. Templates must contain a helpful manifest file in JSON, CommonJS or YAML format.

Installation

Helpful CLI is written using NodeJS and is currently only available via npm. Run the following npm command to install. Once installed, you can access Helpful CLI using the helpme command in your terminal of choice.

npm install -g helpful-cli

Usage

  1. Find a repository that contains a helpful.json, helpful.js or helpful.yml manifest file.
  2. Change to a local directory that you would like to unpack the template into.
  3. Run helpme install <template_url> to start the installer.
  4. Follow the instructions in the prompt.

Or...

mkdir Example
cd Example
helpme install helpfulhuman/cli-example

Creating Templates

Helpful CLI can be used with just about any codebase, existing or otherwise. There are 2 requirements for creating a Helpful CLI compliant package.

  1. A properly constructed and formatted manifest file.
  2. Your template must be hosted by a supported remote type.

The helpful Manifest File

The helpful manifest file is a JSON, CommonJS or YAML file that provides a list of instructions to the Helpful CLI tool. The format of this file can be summed up as "ask, copy, run". The basic template for a manifest file looks like this...

JSON
{
  "ask": [],
  "copy": [],
  "run": []
}
CommonJS

This format allows you to use all the NodeJS runtime has to offer and can be useful for greater control when handling conditionals based on user input.

module.exports = {
  ask: [],
  copy: [],
  run: []
};
YAML
ask:
copy:
run:

Ask

The ask portion of your manifest file contains a list of "question" objects. These objects are used to create terminal prompts that will collect configuration choices from your template's user. This input will allow you to alter Helpful CLI's behaviour when copying files and running scripts.

Helpful CLI currently uses inquirer under the hood and fully supports its question object API. We're only covering the basics here, so feel free to look at their documentation for more info.

Question Object (Basics)
NameTypeDescription
typeStringDefaults to input. The type of question prompt presented to the user. Possible options include input, confirm, list, and checkbox.
nameStringRequired. The variable name that will store the captured user input.
messageStringRequired. The message that will be displayed to the user.
defaultMixedDefault value(s) to use if nothing is entered.
choicesArrayRequired with list and checkbox. Values can be simple strings, or objects containing a name (to display in list), a value (to save in the answers hash) and a short (to display after selection) properties.
Example
{
  "ask": [
    {
      "name": "projectName",
      "message": "What is the name of your project?"
    },
    {
      "type": "list",
      "name": "deployTarget",
      "message": "What is your project's target deployment environment?",
      "choices": [ "AWS", "Docker", "Heroku" ]
    }
  ]
}

Copy

The copy property is an array containing "copy operation" objects. This tells Helpful CLI what to copy from the template to the target directory. All file locations are relative to where the manifest file is.

It's worth noting that every file that is copied is also run through the Nunjucks templating engine. This allows you to customize templates with the user input you collected in the ask step. For more information, check out the Nunjucks templating docs.

Copy Operation Object
NameTypeDescription
pathStringRequired. Can be a path to a file, folder or a glob.
exclude`StringArray`
overwriteBooleanDefaults to false. When true, the copy operation will replace any existing folders at the file's destination with the new one. Use this wisely!
renameFileStringAllows you to rename a file to the set string. Useful for copying over files like _gitignore as .gitgnore. Do not use with glob patterns or directories!
renameDirStringOptionally change the directory that the file(s) will be copied to, relative to the target directory's root.
when`StringFunction`
Example
{
  "copy": [
    {
      "path": "package.json"
    },
    {
      "path": "_gitignore",
      "renameFile": ".gitignore"
    },
    {
      "path": "src/**/*.js",
      "overwrite": true
    }
  ]
}

Run

Finally, the run field is an array of "command objects". These objects represent shell commands that can be run in the target directory. Like the template files in the copy step, each command is run through the Nunjucks templating engine. This allows you to customize your commands with the input collected in the ask step.

Command Object
NameTypeDescription
cmdStringRequired. The shell command to run. Will be parsed by Nunjucks.
when`StringFunction`
Example
{
  "ask": [
    {
      "type": "checkbox",
      "name": "libs",
      "message": "Would you like to install any of these libraries?",
      "choices": ["lodash", "jquery", "rx"]
    }
  ],
  "run": [
    {
      "cmd": "npm install -S {{ libs | join(' ') }}",
      "when": "libs.length > 0"
    }
  ]
}

Final Message on Success

It's not unlikely that you'll want to include a closing message upon successful installation of your template. You can do this using an object for a done property. The done property contains only a "Done object", which is outlined below.

Done Object
NameTypeDescription
messageStringRequired. The message will be output as the final statement upon successful installation of a template. Will be parsed by Nunjucks.
when`StringFunction`
Example
{
  "done": {
    "message": "Run `npm start` to see your application"
  }
}

Using when Strings

Doing any kind of circumstancial or dynamic checking with static files like JSON or YAML is difficult. To circumvent this limitation, we've implemented the when property for copy and run objects. This property can take a string as an alternative that will be treated as a JS expression that only has access to user input (from the ask step).

Here's a quick sample of how it can be used.

{
  "ask": [
    {
      "type": "confirm",
      "name": "createReadme",
      "message": "Would you like to add a README file?"
    }
  ],
  "copy": [
    {
      "path": "README.md",
      "overwrite": true,
      "when": "createReadme == true"
    }
  ]
}

Supported Remotes

These are the remotes currently supported by Helpful CLI.

Public GitHub repositories

GitHub is probably the easiest way to host your template. You can download a GitHub hosted template using either of of the following methods.

helpme install username/repository
helpme install github.com/username/repository
Publicly accessible .zip files

You can host a .zip template anywhere you like, but you need to make sure that the full URL (with a .zip extensions) is provided in order to download.

helpme install http://mydomain.com/files/my-template.zip
Planned Remote Support
  • GitHub (private)
  • BitBucket (public and private)
  • GitLab (public and private)
  • .zip files (authenticated)

Keywords

FAQs

Package last updated on 25 Feb 2017

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc