kamicut / directory-command

use directory structure to define a cli tool's commands and nested subcommands

directory-command

About

Create a command-line tool using directory structure to define nested subcommands.

• Intuitive: Creating new commands is fast and straightforward
• Helpful: Automatically creates help text that is displayed when a user passes the --help flag
• Meticulous: Separates args and flags making them easy to use, and validates the values that are provided

Install

npm install directory-command

Setup

directory-command is designed to make setup as quick as possible.

Use the directory-command cli tool

With npx:

npx directory-command new --name example-cli

Installing globally:

npm i -g directory-command
directory-command new --name example-cli

Make sure to add directory-command to your project dependencies.

Manual setup

Create a bin directory

mkdir bin

Create bin/index.js

touch bin/index.js

#! /usr/bin/env node

const path = require('path')
const directoryCommand = require('directory-command')

const directory = path.join(__dirname, 'commands')

directoryCommand(directory, process.argv.slice(2), {
  commandName: 'example'
})

Create a bin/commands directory

mkdir bin/commands

Create a command

touch bin/commands/index.js

A command file looks like:

function command (args, flags, context) {
  console.log(args, flags, context)
}

const args = []
const flags = []

const options = {
  description: 'example command'
}

module.exports = { command, args, flags }

Args

Args are options that are identified by their position. The order of args matters. The order that you define them in the args array of a command is the order they need to be placed when using the cli tool.

Here's an example definition of an arg:

{
  name: 'hello',
  type: 'string',
  description: 'An arg example for saying hello'
}

Here's how it looks when you use the arg:

example-cli hi

Here's how you use the hello arg in your command:

function command (args, flags, context) {
  console.log(args.hello) // logs `hi`
}

const args = [
  {
    name: 'hello',
    type: 'string',
    description: 'An arg example for saying hello'
  }
]
const flags = []
module.exports = { command, args, flags}

Accessing all args as an array

To get all arg values as an array in their original order, use args._. This array will not include flags, only the values of args as they've been entered on the command line.

Flags

Unlike args, the order that they are defined in does not matter, and they can be placed in any order when using a cli tool.

An example flag definition:

{
  name: 'type-of-day',
  alias: ['d', 'day'],
  type: 'string',
  description: 'An arg example for saying what kind of day it is'
}

Here's how it looks when you use the flag:

example-cli --type-of-day awesome

We set an alias for the flag, so we can use that instead:

example-cli -d awesome

Note that the alias property can be a string with one alias, or an array with multiple strings as shown here. This applies to both args and flags.

Here's how you use the type-of-day flag in your command:

function command (args, flags, context) {
  console.log(flags['type-of-day']) // logs `awesome`
}

const args = []
const flags = [
  {
    name: 'type-of-day',
    alias: ['d', 'day'],
    type: 'string',
    description: 'An arg example for saying what kind of day it is'
  }
]
module.exports = { command, args, flags}

Creating subcommands

Subcommands can be nested as deeply as needed.

A file placed either at:

bin/commands/new/index.js

or:

bin/commands/new.js

can be called with:

example-cli new

A file placed at:

bin/commands/new/example.js

can be called with:

example-cli new example

Default/root command

The default command is the index.js file of the specified commands directory. See the basic usage example.

Documentation

• API
• Tests

Examples

• Basic example

Contributing

Contributions are welcome! Please read the contributing guidelines first.

Conduct

It's important that this project contributes to a friendly, safe, and welcoming environment for all. Read this project's code of conduct

Change log

Read about the changes to this project in CHANGELOG.md. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Contact

• issues – Please open issues in the issues queue

License

ISC