Custom Menu CLI

Português (Brasil)

This is a command-line interface (CLI) tool that creates an interactive menu based on a JSON file. It's designed to simplify the execution of frequent commands in a terminal.

Features

• Interactive menu in the terminal.
• Menu structure defined by a JSON file.
• Easy to configure and use.
• Support for command execution with confirmation.
• Execute action sequences directly from the command line.
• Improved internal structure by unifying action execution logic.
• Enhanced dependency validation with recursion depth checks to prevent excessive nesting.

Releases

You can find all released versions and pre-compiled standalone executables on the GitHub Releases page.

Installation

To install this tool globally, run the following command:

npm install -g custom-menu-cli

Usage

There are three main ways to use this tool:

1. As an Executable (Release Build)

You can generate executables for Linux, macOS, and Windows. After the build, the files will be in the dist/ folder.

First, generate the files with the command:

npm run build

Then, run the file corresponding to your operating system, optionally passing the path to a menu file. If no path is provided, it will look for a menu.json in the current directory.

# On Linux/macOS
./dist/custom-menu-linux [path/to/your/menu.json]

# On Windows
.\dist\custom-menu-win.exe [path\to\your\menu.json]

2. Globally via NPM

Install the package globally to use the custom-menu-cli command anywhere on your system.

npm install -g custom-menu-cli

Once installed, run the command:

custom-menu-cli [path/to/your/menu.json]

3. Programmatically via require

You can import the runCli function into your own Node.js projects to integrate the menu functionality.

First, add the package as a dependency to your project:

npm install custom-menu-cli

Then, use it in your code:

const { runCli } = require('custom-menu-cli');

async function startMyCustomMenu() {
    console.log("Starting custom menu...");
    // Optionally, pass the path to your menu.json file
    await runCli('./path/to/your/menu.json');
    console.log("Custom menu finished.");
}

startMyCustomMenu();

4. Folder-based Menu Generation

The custom-menu-cli now supports generating menus from a structured folder containing JSON files. This allows for better organization and modularity of your menu definitions.

Example Structure (test_menus/):

test_menus/
├── 1-project-a/
│   ├── 1.1-down-service.json
│   ├── 1.2-up-service.json
│   └── 1.3-restart-project-a.json
├── 2-restart-all.json
└── 3-restart-project-a-nested.json

Each .json file within the folder (and its subfolders) represents a menu option. Directories are automatically converted into navigation type options.

How to use:

Simply pass the path to your menu folder as an argument:

custom-menu-cli ./path/to/your/menu_folder

The CLI will automatically discover and combine all valid JSON files into a single menu structure.

5. Command-Line Action Execution

You can execute a sequence of actions directly from the command line without entering the interactive menu. This is useful for scripting and automation.

Usage:

node index.js menu=<path-to-menu> custom-action=<action_id_1>,<action_id_2>,...

• menu=<path-to-menu>: The path to your menu file or directory.
• custom-action=<action_ids>: A comma-separated list of action IDs to execute in sequence.

Examples:

# Execute a single action
node index.js menu=menu.json custom-action=1.1

# Execute a sequence of actions
node index.js menu=./test_menus/ custom-action=1.1,1.2

Recursion Depth Validation:

The tool now includes recursion depth validation to prevent excessively deep nested custom actions and potential infinite loops. If a sequence of custom actions exceeds a predefined maximum recursion depth, the tool will detect it and refuse to execute, displaying an error message. This helps maintain stability and predictability in complex menu structures.

JSON Structure

The JSON file that defines the menu has the following structure:

{
  "name": "custom-menu-cli",
  "description": "JSON-based terminal menu",
  "options": [
    {
      "id": "1",
      "name": "Projeto A",
      "type": "navigation",
      "options": [
        {
          "id": "1.1",
          "name": "Down Service",
          "type": "action",
          "command": "echo 'Down A'",
          "confirm": true
        },
        {
          "id": "1.2",
          "name": "Up Service",
          "type": "action",
          "command": "echo 'Up A'"
        },
        {
          "id": "1.3",
          "name": "Restart Project A (from inside)",
          "type": "custom-action",
          "idList": ["1.1", "1.2"],
          "confirm": true
        }
      ]
    },
    {
      "id": "2",
      "name": "Restart All",
      "type": "custom-action",
      "idList": ["1.1", "1.2"],
      "confirm": true
    },
    {
      "id": "3",
      "name": "Restart Project A (Nested)",
      "type": "custom-action",
      "idList": ["1.3"],
      "confirm": true
    }
  ]
}

Fields

• name: The name of the menu.
• description: A brief description of the menu.
• options: An array of menu options.
  • id: A unique identifier for the option.
  • name: The text that will be displayed for the option.
  • type: The type of option. It can be action (executes a command), navigation (opens a submenu) or custom-action (executes a list of commands from other actions).
  • command: The command to be executed (if the type is action).
  • idList: A list of ids from other actions to be executed (if the type is custom-action).
  • confirm: A boolean that indicates whether a confirmation should be requested before executing the command.
  • options: An array of sub-options (if the type is navigation).

License

This project is licensed under the MIT License.

Author

• Mateus Medeiros
  • GitHub: @mateusmed
  • LinkedIn: Mateus Medeiros