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

• Intuitive: Creating nested commands is fast and straightforward
• Helpful: Automatically prints 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

npm install directory-command

This module requires node version >=14.13.0.

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

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 with npm i directory-command.

mkdir bin

touch bin/index.js

#! /usr/bin/env node

import { dirname, join } from 'path'
import { fileURLToPath } from 'url'
import directoryCommand from 'directory-command'

const __dirname = dirname(fileURLToPath(import.meta.url))
const directory = join(__dirname, 'commands')

const config = {
  commandName: 'example-cli',
  directory,
  argv: process.argv.slice(2),
  context: {}
}

try {
  directoryCommand(config)
} catch (err) {
  console.error(err)
}

mkdir bin/commands

touch bin/commands/index.js

A command file looks like:

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

export const args = []
export const flags = []

export const options = {
  description: 'example command'
}

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:

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

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

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.

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:

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

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

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

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

• API
• Tests

• Basic example

Contributions are welcome! Please read the contributing guidelines first.

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

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.

• issues – Please open issues in the issues queue

ISC