knevee

knevee simplifies running JavaScript directly from the terminal. It enables users to execute scripts efficiently, providing intuitive CLI interactions.

Overview

knevee allows you to craft lightweight, customizable command-line tools using JavaScript. Define a module, specify the positional arguments and options, and you're ready to run your script with ease.

Example

Here’s a quick example of how a simple greeting command could be implemented:

#!/usr/bin/env knevee
export const description = "Greetings earthling";
export const positionals = "<name>";

export default async (name) => {
  return `hello ${name}`;
};

Usage

You can execute the script directly, view help, and handle various command-line inputs:

$ greeting --help
Usage: greeting <name>
Greetings earthling
    --help Prints command help message

$ greeting michael
hello michael

$ greeting
Missing required positional arguments: <name>

$ greeting michael jordan
Extra positional arguments: jordan

$ greeting "michael jordan"
hello michael jordan

Installation

Install knevee globally using npm to use it from anywhere on your system:

npm install knevee -g

Alternativley you can execute a single file like this

npx knevee ./file.js

Configuration Options

knevee supports a robust set of configuration options to tailor your scripts. Here's what you can customize:

| name | type | doc | | --- | --- | --- | | name | string | string[] | The name of the module. (Defaults to the name of the file) | | description | string | A description of what the module does. | | dependencies | string | string[] | A list of dependencies required by the module. | | positionals | string[] | string | Positional arguments that the module accepts. Can be specified as an array or a space-separated string. | | flags | FlagOptions | A mapping of command line flags to their settings. parseArgs | | default | null | | The function that executes when the command is run. | | useStrictFlags | boolean | Specifies if the flags should be strictly validated against the provided flags definitions. (Defaults to true) | | useUnshiftStdin | boolean | Determines if stdin should be unshifted into args. (Defaults to true) | | useLoopMethod | string | allSettled | all | for-await | When iterating stdin loop uses Promise.allSettled instead of Promise.all. (Defaults to false) | | output | string | boolean | The type of output that the module should produce. (Defaults to log) | | | | - bool - Outputs the result as a boolean value, adds --emoji, --int flags to command. | | | | - json - Outputs the result as a JSON string, pretty prints the result. | | | | - lines - Expects an array, and will output each item on a line. | | | | - log - Prints the value. | | | | - stdout - Prints the value. | | | | - bash - Expects function to return string, and executes, adds --print flag to the command, which prints the string. | | | | - false - Disables output. | | positionalType | PositionalType | undefined | Describes how positional rules translate to function arguments. (Defaults to positionalAsObject) | | | | - positionalNamedObject - Uses name in positionals as key in args. | | | | - positionalAsArray - Uses escalating _ as the key separating -- in positionals. | | stdin | StdinLoopType | boolean | Determines if the module should read from stdin and how. (Defaults to false) | | | | - false - Disables stdin. | | | | - true - Reads from stdin | | | | - loopJson - Reads from stdin as a JSON array and loops over each item. | | | | - loopLines - Reads from stdin as a string and loops over each line. | | | | - loop - Reads stdin and does loopJson with backup to loopLines. | | runtime | undefined | string | string[] | Set the javscript runtime to evaluate subprocesses under, must expect appending js string. | | | | node | | | | --experimental-strip-types | | | | --experimental-detect-module | | | | --disable-warning=MODULE_TYPELESS_PACKAGE_JSON | | | | --disable-warning=ExperimentalWarning | | | | -e | | runtimeKey | string | node | deno | undefined | | path | undefined | string | path to dir or file | | __filename | undefined | string | path to dir or file | | importMeta | undefined | ImportMeta | undefined | | cwd | string | undefined | current working directory | | argv | string[] | undefined | command arguments | | subprocess | boolean | runs the command as a subprocess |

| var | type | description | | --- | --- | --- | | KNEVE_THROW | boolean | Throws Kneve errors instead of just logging the message |