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:

``js
#!/usr/bin/env knevee
export const description = "Greetings earthling";
export const positionals = "";

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

Usage

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

`bash
$ greeting --help
Usage: greeting
Greetings earthling
--help Prints command help message

$ greeting michael
hello michael

$ greeting
Missing required positional arguments:

$ 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:

`bash
npm install knevee -g
`

Alternativley you can execute a single file like this

`bash
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 |