sethvincent / directory-command

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

directory-command

About

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

Install

npm install directory-command

Node version support

This module requires node version >=14.13.0.

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

Manual setup

Create a bin directory

mkdir bin

Create bin/index.js

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)
}

Create a bin/commands directory

mkdir bin/commands

Create a command

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

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 = []

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:

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'
  }
]

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

Changelog

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