Opaline – CLI Tools Framework

Opaline — a CLI tools framework and compiler. It draws inspiration from NextJS(and similar projects) and provides a quick, convention based, way of creating CLI tools.

1. It looks for files in ./commands folder and treats them as commands for a CLI:

   • commands
     └── build.ts
     
     # Means it can be run as following:
     λ cli build
     

2. Command file must export a function (can be async function too):

   • export default function myCommand() {}
     // or
     module.exports = async function myCommand() {};

3. Uses JSDoc to describe parameters and documentation for a CLI. Read more on supported JSDoc syntax and how to use it here.

Table of Contents

• Table of Contents
• Usage
• Creating Commands
  • Adding Command Parameters and Documentation
    • Using unnamed arguments
• JSDoc
  • Supported JSDoc Tags
  • Extra JSDoc Tags
• package.json
  • package.json#bin
  • package.json#description
• Examples
• Screenshots

Usage

Use a generator to bootstrap an Opaline based CLI:

λ npx @opaline/core create app
λ cd app
λ npm install

Compile the CLI:

λ npm run build
λ npm run dev # for dev mode with watch and auto linking

Creating Commands

By default generator creates commands/index.js file, which is a default command, and can be run without specifying a command name:

λ cli --param1 20

But if required there might be multiple commands in one CLI. In order to do that, we just need to create another file in ./commands folder (or rename index.js, it's not required to have a default command):

// ./commands/build.js

export default function build() {
  console.log("hello build!");
}

Adding Command Parameters and Documentation

Opaline uses JSDoc to define parameters and documentation for a command.

Using unnamed arguments

Opaline can pass all non-flag arguments to a command, for this command needs to define an $inputs argument in the JSDoc as shown below:

// ./commands/build.js
/**
 * Description of a command is just a comment above the command's function.
 * Params are described as JSDoc params:
 *
 * @param {Array<string>} $inputs Any non-flag arguments are passed here
 */
export default function build($inputs) {
  console.log(`hello ${name}, language ${lang}`);
}

It's also possible to define named (flag) arguments:

// ./commands/build.js

/**
 * Description of a command is just a comment above the command's function.
 * Params are described as JSDoc params:
 *
 * @param {Array<string>} $input Any non-flag arguments are passed here
 * @param {string} name Name of an app to build
 * @param {string} [lang="TypeScript"] A parameter with default value
 */
export default function build($inputs, name, lang) {
  console.log(`hello ${name}, language ${lang}`);
}

Help will be generated for both default and this new command:

λ examples-for-docs --help # help for the whole cli, with list of commands

VERSION
  examples-for-docs/0.0.0

USAGE
  examples-for-docs inputs --param1 10 --param2 20

COMMANDS
  build     Description of a command is just a comment above the command's function. Params are described as JSDoc params:

> NOTE: To view the usage information for a specific command, run 'examples-for-docs [COMMAND] --help'

OPTIONS
  --param1      Some parameter for a CLI with a default value [number] [default: 20]
  --param2      Some parameter for a CLI [string]
  --help        Output usage information
  --version     Output the version number




λ examples-for-docs build --help # help for a subcommand

Description of a command is just a comment above the command's function. Params are described as JSDoc params:

OPTIONS
  --name     Name of an app to build [string]
  --lang     A parameter with default value [string] [default: "TypeScript"]

JSDoc

Opaline uses JSDoc to describe command's parameters and documentation.

Supported JSDoc Tags

Tag	Description
@param – https://jsdoc.app/tags-param.html	Supports primitive types: string, number, boolean. And arrays of strings string[]
@example	Note: only one line examples: @example {cliName} --params 10

Extra JSDoc Tags

Tag	Description
@param $inputs	Indicates that command receives unnamed arguments
@usage	Similar to example, but outlines the main example on how to use a CLI command. @usage {cliName} build
@short	Defines an alias (shortcut) for a parameter. @short name=n
{cliName}	A variable that will be replaced by the name of a CLI tool described in package.json. Supported by @usage and @example

package.json

Opaline gets multiple things from a package.json file, to even more reduce configuration:

package.json#bin

https://docs.npmjs.com/files/package.json#bin

There are 2 way of using the bin field in package.json:

// 1
{
  "name": "cli-name",
  "bin": "./cli/cli.js"
}

// 2
{
  "name": "cli-name",
  "bin": {
    "cli-name": "./cli/cli.js"
  }
}

Opaline supports both of them. And uses those fields in a following way:

1. Path to a CLI file – For both cases the file path is used as an output target for a CLI entry point, and will be automatically created by Opaline, no need to manually create it.
2. Name of a CLI – For [1] the name will be package.json#name, if you need to have a different name than the name of a package, use an option 2. Name is used as {cliName} in JSDoc and also when linking packages in dev mode. Which makes them accessible globally, by this name:
   • cli-name [COMMAND]

package.json#description

Used as main description for a CLI tool.

Examples

Tools built with Opaline:

• Opaline CLI itself
• Example Choose Reviewer Tool
• Using JSX and Ink
  • Ink

Screenshots