clinei

command-line interface handler

clinei is handler to facilitate the building of cli programs with stability and also you can specify the type of entry of each command and customization that helps you write a clean program clinei is not a cli package, it is a package that helps you build a cli package

Features

• ✅ Command
• ✅ Option
• ✅ Argument
• ✅ Help
• ✅ Version
• ✅ Customization
• ✅ Type
• ✅ Alias
• ✅ Default
• ✅ Required
• ✅ Description
• ✅ Example

Support

• ✅ ECMAScript Modules (ESM)
• ✅ CommonJS (CJS)
• ❌️ Deno

Map

• Examples

• Installation

  • NPM
  • yarn

• Build

  • esm (ECMAScript Modules)
  • cjs (CommonJS)

• Command

  • CommandConfig
    • cmd
    • desc
    • options
    • usage
    • FinalConfiguration
  • CommandConfigOption
    • name
    • desc
    • type
    • msg
    • required
    • default
  • Methods
    • getOptions()
    • getArgs()
    • parseArgs()
    • exist()
    • getStructure
    • printHelp
  • HelpCommand (required)
  • Make Cli Global

Examples

index.js

#!/usr/bin/env node
import { Build } from "clinei";
import path from "path";
import { fileURLToPath } from "url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
new Build({
  path: __dirname + "/commands",
  prefix: " real-cli",
});

if You use CommonJS

- import
+ require

+ const { Build } = require("clinei");
- import { Build } from "clinei";
- import path from "path";
- import { fileURLToPath } from "url";
- const __dirname = path.dirname(fileURLToPath(import.meta.url));
+ new Build({
+   path: __dirname + "/commands",
+   prefix: " real-cli",
+ });

and
+ module.exports = Command(...);
- export default Command(...);

commands/print.js

import { Command } from "clinei";
export default Command(
  {
    cmd: "print", //or ["print","--print","-p","myprint"] //with aliases for this command
    desc: "Log in and print data in console",
    options: [
      {
        name: ["--username", "-u"], //with aliases
        desc: "your real name",
        required: true,
      },
      {
        name: "--age", //no aliases
        desc: "your real age",
        type: "number",
        msg: "See the documentation for more information on github",
        default: 99,
      },
      {
        name: "--store", //no aliases
        desc: "store your data or no (optional)",
      },
    ],
    usage: "print pro -u Arth --age=101 --store --skills 1 2 3 4 5 6",
  },
  ({ getOptions, exist, getArgs, parseArgs }) => {
    const username = getOptions("--username"); // or -u
    const age = getOptions("--age");
    const store = exist("--store");
    const Skills = parseArgs("--skills"); //or any other key like --
    if (getArgs("pro")) {
      console.log(
        `[${getArgs()[0]}] Hi ,${username} Your Data Enjoy!
      
  [username] ${username}
  [age] ${age}
  [store] ${store ? "yes store my data" : "No!"}
  [skills] ${Skills.join(", ")}
`
      );
    } else
      console.log(
        `[noob] Hi ,${username} Your Data Enjoy!
    
[username] ${username}
[age] ${age}
[store] ${store ? "yes store my data" : "No!"}
[skills] ${Skills.join(", ")}
`
      );
  }
);

commands/help.js

import { Command } from "clinei";
export default Command(
  {
    cmd: ["-h", "--help", "help"], // <-- This is the command name like <Prefix> help <command>
    desc: "View Commands", // <-- This is the command desc
    usage: "help <command>",
  },
  ({ printHelp, getArgs, getStructure }, focus) => {
    console.log(printHelp);
    if (
      (getArgs()[0] || focus) &&
      !getStructure.commands.find(({ cmd }) =>
        cmd.find((c) => c === focus || c === getArgs()[0])
      )
    ) {
      console.log(`Warn: ${`["${getArgs()[0] || focus}"]`} not found`);
    }
  }
);

Run

node index.js print -u Arth --age 120 --store

OutPut

[noob] Hi ,Arth Your Data Enjoy!

[username] Arth
[age] 120
[store] yes store my data
[skills]

Installation

NPM

npm i clinei

yarn

yarn add clinei

Build

Build is a class that is responsible for building the cli program, it is necessary to pass the path of the commands folder and the prefix of the program

We use real-cli as an example

import { Build } from "clinei";
import path from "path";
import { fileURLToPath } from "url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
new Build({
  path: __dirname + "/<commands folder>",
  prefix: "real-cli", //<prefix>
});

const { Build } = require("clinei");
new Build({
  path: __dirname + "/<commands folder>",
  prefix: "real-cli", //<prefix>
});

Command

/<commands folder>/**/*.js Command() a function that registers the command in the program

import { Command } from "clinei";
export default Command(
  {
    cmd: [], // or string
    desc: "",
    usage: "",
    options: [],
  },
  ({ <Methods> }) => {
    // code
    }
);

const { Command } = require("clinei");
module.exports = Command(
  {
    cmd: [], // or string
    desc: "",
    usage: "",
    options: [],
  },
  ({ <Methods> }) => {
    // code
    }
);

CommandConfig

{
  cmd: [],
  desc: "",
  usage: "",
  options: [...],
}

cmd

cmd is the command that will be executed in the program, it can be a string or an array of strings

no alias

$ real-cli print

{
  cmd: "print",
}

with alias

-p or --print or print

$ real-cli -p

{
  cmd: ["-p", "--print", "print"],
}

desc

desc is the description of the command, it is used in the help command

{
  desc: "Log in and print data in console",
}

options

the options of the command, required if the command has options

see full documentation of CommandConfigOption

usage

usage is the usage of the command, it is used in the help command

{
  usage: "print pro -u Arth --age=101 --store --skills 1 2 3 4 5 6",
}

Finally

 {
    cmd: "print", //or ["print","--print","-p","myprint"] //with aliases for this command
    desc: "Log in and print data in console",
    options: [
      {
        name: ["--username", "-u"], //with aliases
        desc: "your real name",
        required: true,
      },
      {
        name: "--age", //no aliases
        desc: "your real age",
        type: "number",
        msg: "See the documentation for more information on github",
        default: 99,
      },
      {
        name: "--store", //no aliases
        desc: "store your data or no (optional)",
      },
    ],
    usage: "print pro -u Arth --age=101 --store --skills 1 2 3 4 5 6",
  }

CommandConfigOption

ConfigOption is the configuration of the options of the command

default value

{
  name: "",// or array
  desc: "",
  type: "string",
  msg: false,
  required: false,
  default: undefined
}

name

name of the option, it can be a string or an array of strings must start with - or --

no alias

{
  name: "--username",
}

$ real-cli --username Arth

with alias

-u or --username

{
  name: ["-u", "--username"],
}

$ real-cli -u Arth

desc

the description of the option, it is used in the help command

{
  desc: "your real name",
}

type

the type of the option, it is used to validate the option

{
  type: "string" | "number" | "boolean",
}

Type Test

{
  name: "--age", //no aliases
  desc: "your real age",
  type: "number",
  msg: "See the documentation for more information on github",
  default: 99
}

expected number

$ real-cli --age nine

OutPut in interface

Error: Invalid value for option --age expected number got nine
                                                         ^
Tip: use  real-cli help print to see command options

msg

will be displayed if the option is not valid

{
  msg: "See the documentation for more information on github",
}

$ real-cli --age nine

OutPut in interface

Error: Invalid value for option --age expected number got nine
                                                         ^
See the documentation for more information on github

Tip: use  real-cli help print to see command options

required

required is a boolean that indicates if the option is required

  {
    name: ["--username", "-u"], //with   aliases
    desc: "your real name",
    required: true,
  }

$ real-cli --age 99

OutPut in interface

Missing required option --username,-u

Tip: use  real-cli help print to see command options

default

default is the default value of the option

  {
    name: "--age", //no aliases
    desc: "your real age",
    type: "number",
    msg: "See the documentation for more information on github",
    default: 99
  }

$ real-cli

getOptions("--age"); // 99

Methods

Command(
  {
    cmd: [], // or string
    desc: "",
    usage: "",
    options: [],
  },
  ({ getOptions, getArgs, parseArgs, exist, getStructure, printHelp }) => {
    // code
  }
);

getOptions()

returns values of the options passed in the command

specify the name of the option to get the value

getOptions("--username");
// or one of the aliases
getOptions("-u");

all options

getOptions();

getArgs()

returns the arguments passed in the command

getArgs(); // return array

specify the key to get the arguments

getArgs("arg1"); // "arg1" || false

$ real-cli print arg1 arg2 arg3

OutPut getArgs();

["arg1", "arg2", "arg3"]; // if the key exists
[]; // if the key does not exist

getArgs("arg1");

"hi"; // if the key exists
false; // if the key does not exist

parseArgs()

returns the arguments associated with the key passed in the command

-- 1 2 3 4 5

specify the key to get the arguments -- or any other key or string

parseArgs("--");

OutPut Array

[1, 2, 3, 4, 5] // if the key exists
[] // if the key does not exist

exist()

returns a boolean indicating if the option exists

exist("--username");

OutPut Boolean

true; // if the option exists
false; // if the option does not exist

getStructure

returns the structure of the commands You can use it to build a custom help instead printHelp()

getStructure; // return object

OutPut Object

{
  commands: [
  {
  "cmd": [], // or string
  "desc": "",
  "usage": "",
  "options": [...]
  ,...
  }
  ];
  prefix: string;
  //this is the structure of the command that is being executed
  this: {
  "cmd": [], // or string
  "desc": "",
  "usage": "",
  "options": [...]
  }
}

printHelp

printHelp is a property that prints the help of the commands

printHelp;

HelpCommand

HelpCommand is a command that is used to print the help of the commands

Command(
  {
    cmd: ["-h", "--help", "help"],
    desc: "View Commands",
    usage: "help <command>",
  },
  ({ printHelp }) => {
    console.log(printHelp);
  }
);

$ real-cli help

OutPut

usage:  real-cli help <command>

 real-cli -h, --help, help [options] [aliases]
                                                  View Commands
 real-cli print [options] [aliases]
                                                  Log in and print data in console
 Options:
    --username, -u  REQUIRED,STRING
                                                  your real name
    --age  NUMBER
                                                  your real age
    --store  STRING
                                                  store your data or no (optional)

$ real-cli help print

OutPut

usage:  real-cli print pro -u Arth --age=101 --store --skills 1 2 3 4 5 6

 real-cli print [options] [aliases]
                                                  Log in and print data in console
Options:
    --username, -u  REQUIRED,STRING
                                                  your real name
    --age  NUMBER
                                                  your real age
    --store  STRING
                                                  store your data or no (optional)

Command(
  {
    cmd: ["-h", "--help", "help"], // <-- This is the command name like <Prefix> help <command>
    desc: "View Commands", // <-- This is the command desc
    usage: "help <command>",
  },
  ({ printHelp, getArgs, getStructure }, focus) => {
    console.log(printHelp);
    //focus ->> delete
    if (
      (getArgs()[0] || focus) &&
      !getStructure.commands.find(({ cmd }) =>
        cmd.find((c) => c === focus || c === getArgs()[0])
      )
    ) {
      console.log(`Warn: ${`["${getArgs()[0] || focus}"]`} not found`);
    }
  }
);

$ real-cli delete
           ^^^^^^ ->> focus

$ real-cli help delete
                ^^^^^^ ->> getArgs()[0]

OutPut

usage:  real-cli help <command>

 real-cli -h, --help, help [options] [aliases]
                                                  View Commands
 real-cli print [options] [aliases]
                                                  Log in and print data in console
 Options:
    --username, -u  REQUIRED,STRING
                                                  your real name
    --age  NUMBER
                                                  your real age
    --store  STRING
                                                  store your data or no (optional)

Warn: ["delete"] not found

Make Cli Global

Make a global program local use npm

add this to your package.json

{
  "bin": {
    "real-cli": "index.js"
  }
}

run

$ npm link

or publish and install it globally

Example with npm

npm install <package> -g

now you can use your program

$ real-cli help

Links

• Github

License

• Apache-2.0

clinei is a CLI program builder