# Getting Started with CLI Arguments in Node.js — Liran Tal

Learn how to enhance your Node.js CLI applications using the built-in `util.parseArgs` API. This guide covers dual-mode operations, input validation, and testing, using the `agent-rules` project as a case study.

Canonical: https://lirantal.com/blog/mastering-cli-arguments-nodejs

![Cover artwork for Getting Started with CLI Arguments in Node.js](/_astro/cli-arguments-nodejs.CP8H7Mjo_FNThL.jpg)

Command-line interfaces (CLIs) are a powerful way to interact with software, especially for developers who prefer automation and scripting. In this guide, you’ll learn how to enhance your Node.js CLI applications using the built-in `util.parseArgs` API. By exploring the `agent-rules` project, you’ll gain insights into implementing dual-mode operations, validating inputs, and testing your CLI tools effectively. This tutorial is designed for intermediate Node.js developers familiar with CLI tools and basic scripting.

## Prerequisites

Before diving into the tutorial, ensure you have the following:

*   **Node.js**: Current LTS version
*   **Basic knowledge**: Familiarity with CLI tools and Node.js scripting
*   **Git**: For cloning repositories

## Setting Up the Environment

To get started, you’ll need to set up your development environment. Follow these steps to clone the `agent-rules` repository and install the necessary dependencies.

### 1\. Clone the Repository

The `agent-rules` project is a CLI tool designed to generate security-focused instructions for AI coding assistants. Start by cloning the repository:

```
git clone https://github.com/lirantal/agent-rules.git
cd agent-rules
```

### 2\. Install Dependencies

Next, install the required Node.js packages using npm:

```
npm install
```

This step ensures that all necessary packages are available for the project to run smoothly.

## Understanding CLI Argument Parsing

Node.js provides a built-in API for parsing command-line arguments, which simplifies the process of handling user inputs. The `util.parseArgs` API is a powerful tool for this purpose.

### Why Use `util.parseArgs`?

Using built-in Node.js modules for CLI development offers several benefits:

*   **Simplicity**: Reduces the need for external dependencies.
*   **Performance**: Optimized for Node.js runtime.
*   **Security**: Minimizes the risk of injection attacks by validating inputs.

### Example: Parsing Command-Line Arguments

Here’s a basic example of how to parse command-line arguments using `util.parseArgs`:

```
import { parseArgs } from 'node:util';

function parseCommandLineArgs(): CliArgs {
  const { values } = parseArgs({
    args: process.argv.slice(2),
    options: {
      app: { type: 'string', short: 'a' },
      topics: { type: 'string', multiple: true, short: 't' },
      help: { type: 'boolean', short: 'h' },
      version: { type: 'boolean', short: 'v' }
    }
  });
  return values;
}
```

**Why this matters**: This function demonstrates how to set up argument parsing using Node.js built-in utilities.

**Verify**: Run the CLI with various flags to see parsed output.

## Implementing Dual-Mode CLI

The `agent-rules` project supports both interactive and automated workflows. This dual-mode operation is crucial for flexibility in different environments.

### Step-by-Step Guide

1.  **Add Command-Line Argument Support**

    Modify your CLI application to accept command-line arguments. This involves defining the expected options and their types.

    ```
    const args = parseCommandLineArgs();
    ```

2.  **Implement Interactive Mode**

    Use the `@clack/prompts` library to create an interactive session when no arguments are provided.

    ```
    import { prompt } from '@clack/prompts';

    async function interactiveMode() {
      const app = await prompt('Enter the app name:');
      const topics = await prompt('Enter topics (comma-separated):');
      // Process inputs
    }
    ```

3.  **Switch Between Modes**

    Determine the mode based on the presence of command-line arguments.

    ```
    if (Object.keys(args).length === 0) {
      interactiveMode();
    } else {
      // Process command-line arguments
    }
    ```


**Why this matters**: Dual-mode operation allows users to choose between automation and manual interaction, enhancing usability.

## Validating and Handling Arguments

Proper validation and error handling are essential for robust CLI applications. This ensures that users receive clear feedback when they provide invalid inputs.

### Techniques for Validation

1.  **Validate CLI Inputs**

    Ensure that the provided arguments meet the expected criteria.

    ```
    function validateCliArgs(args: CliArgs): void {
      if (args.app && !AVAILABLE_APPS.includes(args.app)) {
        console.error(`Error: Invalid app "${args.app}". Available apps: ${AVAILABLE_APPS.join(', ')}`);
        process.exit(1);
      }
    }
    ```

    **Why this matters**: Validating inputs prevents errors and provides helpful feedback to users.

    **Verify**: Test with invalid app names to trigger validation errors.

2.  **Handle Errors Gracefully**

    Use try-catch blocks to manage unexpected errors and provide meaningful messages.

    ```
    try {
      validateCliArgs(args);
    } catch (error) {
      console.error('An error occurred:', error.message);
      process.exit(1);
    }
    ```


**Why this matters**: Effective error handling improves the user experience by preventing crashes and guiding users to correct their inputs.

## Testing CLI Applications

Testing is a critical part of developing reliable CLI tools. It ensures that your application behaves as expected under various scenarios.

### Writing Unit Tests

1.  **Test Argument Parsing**

    Use the Node.js `assert` module to write unit tests for your argument parsing logic.

    ```
    import assert from 'node:assert';

    assert.deepStrictEqual(parseCommandLineArgs(['--app', 'myApp']), { app: 'myApp' });
    ```

2.  **Simulate CLI Interactions**

    Use `spawnSync` to simulate command-line interactions in your tests.

    ```
    import { spawnSync } from 'node:child_process';

    const result = spawnSync('node', ['cli.js', '--app', 'myApp']);
    assert.strictEqual(result.status, 0);
    ```


**Why this matters**: Testing ensures that your CLI application handles different input scenarios correctly and reliably.

## Conclusion

By mastering CLI argument parsing in Node.js, you can build powerful and flexible command-line tools. This guide covered the essentials of using the `util.parseArgs` API, implementing dual-mode operations, validating inputs, and testing your applications. With these skills, you’re well-equipped to enhance your Node.js CLI projects.

*   **Try the updated `agent-rules` CLI** with your own AI app configurations.
*   **Follow on X/Twitter for new guides and security research.**
*   **Explore more code examples and related work on GitHub.**

For further reading, check out the [Node.js `util` module documentation](https://nodejs.org/dist/latest-v18.x/docs/api/util.html#utilparseargsconfig) and the [Agent Rules GitHub Repository](https://github.com/lirantal/agent-rules).

## More writing

[All writing](/blog)

*   Sep 5, 2026

    ### [Self-Hosting Hermes Agent with Matrix E2EE on Proxmox](/blog/self-host-hermes-agent-matrix-e2ee-proxmox)

*   Aug 2, 2026

    ### [The Practical Second Brain: Building an LLM-Operated Markdown Knowledge Graph](/blog/practical-second-brain-llm-markdown-knowledge-graph)

*   Aug 1, 2026

    ### [Building a Second Brain with LLMs and AI Agents](/blog/building-second-brain-llms-ai-agents)


* * *

Liran Tal is the author of the book [Node.js Secure Coding: Defending Against Command Injection Vulnerabilities](https://www.nodejs-security.com/)

[Start Building Secure Node.js Applications](https://www.nodejs-security.com/)

 [![](/_astro/nodejs-secure-coding-book-3d-style.DiTWpzFs_Z3c7s1.png)](https://www.nodejs-security.com/)