NLEX Documentation

NLEX (Natural Language Shell Executor) is a command-line tool designed to bridge the gap between natural language and shell commands. It allows you to describe tasks in plain English, which NLEX then translates into executable commands for your chosen shell (e.g., Bash, Zsh, PowerShell).

Powered by Google's Gemini models, NLEX can also provide explanations for generated commands, analyze them for potential security risks, and summarize command output in a user-friendly way.

NLEX Version: 0.0.1. Copyright (c) 2025 Pewrie Bontal (https://bontal.net).

NLEX can be installed with a single command. Open your terminal and run:

curl -sSL https://nlex.bontal.net/install.sh | bash

This script downloads the NLEX binary and attempts to place it in a directory within your PATH. Currently, the installer is primarily targeted for Linux-like environments. Windows and macOS specific installers may be available in the future.

By downloading and using NLEX, you agree to the Terms of Service.

The first time you run NLEX, it will guide you through an interactive setup process if a configuration file is not found or is incomplete. This setup includes:

• AI Provider API Key: NLEX requires an API key for its AI model to function. You'll be prompted to enter your key. This key is stored locally in your NLEX configuration file.
• Shell Selection: NLEX detects available shells on your system (e.g., bash, zsh, powershell) and prompts you to select your preferred shell for command execution.
• Default Behaviors: You'll be asked to set preferences for:
  • Confirm commands by default (default_confirm)
  • Enable command history (history_enabled)
  • Enable context awareness from history (context_awareness)
  • Enable neutral AI-summarized output (neutral_enabled)
  • Enable command explanation (explanation_enabled)
  • Enable security analysis (security_analysis_enabled)
• Max History Items: If history is enabled, you can set the maximum number of commands to store.

Once completed, your settings are saved to ~/.nlex/config.json.

Command Line Interface (CLI)

You can use NLEX directly from your terminal in two main ways:

1. Direct Command Execution:

   Provide your natural language query directly after the nlex command:

   nlex [options] your natural language command here

   Example:

   nlex list all text files in the current directory modified in the last 2 days

2. Interactive Mode:

   Start NLEX in interactive mode by running:

   nlex

   Or explicitly:

   nlex -i

   This will present you with an [nlex]: prompt where you can type your natural language commands or use NLEX's built-in interactive commands (prefixed with !).

CLI Options (Flags)

NLEX supports the following command-line flags:

• -version: Display NLEX version and copyright information.
• -y: Automatically confirm and execute commands (bypasses interactive confirmation).
• -i: Start in interactive mode.
• -n: Return results in neutral language using AI analysis (summarizes output). Overrides config default.
• -nx: Skip command explanation. Overrides config default.
• -ns: Skip security analysis. Overrides config default.

You can see these options by running nlex --help or nlex -h.

When in interactive mode (started with nlex or nlex -i), you can use the following special commands prefixed with an exclamation mark (!):

• !help: Displays usage information, CLI options, and available interactive commands.
• !history or !hist: Shows your NLEX command history.
  • !hist <number>: Re-runs the natural language command from the specified history number.
• !shell [shell_name]:
  • With no argument, displays the currently selected shell and lists available shells.
  • With [shell_name] (e.g., !shell zsh), changes the selected shell for NLEX.
• !config [key] [value]: Manages NLEX configuration.
  • With no arguments, shows all current configuration settings.
  • With [key] (e.g., !config api_key), shows the value of that specific setting.
  • With [key] [value] (e.g., !config default_confirm false), updates the setting.
• !clear: Clears the terminal screen.
• !sysinfo: Displays collected system information that NLEX uses for context.
• !refresh-sysinfo: Forces a refresh of the cached system information.
• !exit or !quit: Exits NLEX interactive mode. (You can also use exit or quit without the '!' prefix).

NLEX has built-in handling for a few common shell commands. These are executed directly by NLEX without necessarily invoking its advanced processing engine, providing faster execution for these specific operations. They can be used via natural language or by typing the command directly in interactive mode.

• cd [directory]: Changes the current working directory context used by NLEX. NLEX maintains its own understanding of the current directory to help generate accurate commands. This cd affects NLEX's context for subsequent commands, not necessarily the shell prompt you return to after NLEX exits (unless NLEX itself is your primary shell wrapper). Supports ~ and ~/path.
• pwd: Prints NLEX's understanding of the current working directory.
• echo [args...]: Prints the arguments to the standard output.

• Natural Language to Shell Command Translation: The primary function. Type what you want to do, and NLEX (via its AI model, like Gemini) attempts to generate the correct shell command.
• Command Confirmation: By default (default_confirm: true), NLEX will show you the generated command and ask for confirmation before executing it. Press Enter to confirm, or type anything and Enter to cancel. This can be bypassed with the -y CLI flag.
• Command Explanation: If enabled (explanation_enabled: true), NLEX provides a brief explanation of the generated shell command before confirmation. Can be skipped with -nx.
• Security Analysis: If enabled (security_analysis_enabled: true), NLEX analyzes the generated command for potential security risks (e.g., destructive operations, data exposure). It provides a risk level (LOW, MEDIUM, HIGH, CRITICAL) and a description. Can be skipped with -ns. Always review commands, especially those flagged with higher risk levels.
• Neutral Output Summarization: If enabled (neutral_enabled: true or with -n flag), NLEX uses its AI model to rephrase the raw output of executed commands into a concise, natural language answer.
• Context Awareness: If enabled (context_awareness: true), NLEX includes snippets of recent command history (NL query, shell command, exit code, truncated output) in its prompts to the AI model. This helps the AI generate more relevant follow-up commands.
• Clipboard Copy (Non-Interactive): When running a direct command (not in interactive mode) and if confirmation is not skipped and AI features like neutral output/explanation/security are not active, the generated command is automatically copied to the clipboard.

NLEX stores its configuration in a JSON file located at ~/.nlex/config.json. You can manage most settings using the !config command in interactive mode.

Key Configuration Options:

NLEX stores its operational data in the ~/.nlex directory:

• config.json: Stores user configuration, including the API key (masked in CLI display), shell preferences, feature toggles, etc.
• history.json: If history is enabled, this file logs your natural language commands, the generated shell commands, timestamps, exit codes, and truncated output of commands.
• sysinfo.json: Caches collected system information (OS, distribution, CPU, RAM, installed tools, key environment variables) to provide context to the AI model for more accurate command generation. This information is updated periodically or can be manually refreshed with !refresh-sysinfo.
• nlex_history: Stores the command line history specifically for the NLEX interactive prompt (readline history).

Be mindful that your API key and command history (which might contain sensitive information depending on your commands) are stored locally on your machine.

NLEX attempts to detect common shells available on your system. During the first-time setup, or via the !shell command, you can choose your preferred shell for command execution.

Commonly detected shells include:

• Linux/macOS: bash, zsh, sh, ksh, fish
• Windows: powershell, cmd

NLEX uses the selected shell's execution arguments (e.g., -c for bash/zsh, -Command for PowerShell) to run the generated commands.

NLEX's core AI functionalities (command generation, explanation, security analysis, summarization) rely on a third-party AI service, such as Google Gemini. You must provide your own API key for this service.

• The API key is configured during the first-time setup or can be updated using !config api_key YOUR_KEY.
• It is stored in ~/.nlex/config.json. While NLEX masks it when displaying the config via !config, the key is stored in plaintext in the file. Ensure this file is adequately protected.
• If the API key is invalid or missing, AI-dependent features will not work. NLEX will typically warn you about this.
• All API usage is subject to the terms and pricing of the respective AI service provider (e.g., Google).

• API Key Not Configured: If you see errors like "API key not configured" or "AI client error," ensure your AI provider API key (e.g., for Google Gemini) is correctly set using !config api_key YOUR_KEY.
• Command Generation Blocked: Occasionally, the AI model might refuse to generate a command if it deems the request unsafe, ambiguous, or against its usage policies (e.g., Google's Gemini safety policies). The error message usually indicates the reason (e.g., "BlockReasonSafety"). Try rephrasing your request.
• Shell Built-ins vs. AI Commands: Simple commands like cd, pwd, and echo are handled directly by NLEX. More complex requests are sent to the AI model.
• Context is Key: The quality of AI-generated commands often depends on the clarity of your natural language input and, if context awareness is enabled, relevant recent history. Providing specific details usually yields better results.
• Security: While NLEX offers security analysis, it is not infallible. Always review commands before execution, especially those modifying files, installing software, or accessing sensitive data. You are responsible for the commands you run.