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.
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