Neural Shell (nlsh): Your AI-Powered Command Line Assistant

Evander Q. L. Darrow — Sat, 05 Apr 2025 18:20:27 +0000

Neural Shell (nlsh): Your AI-Powered Command Line Assistant

Have you ever found yourself spending precious minutes Googling the right shell commands or asking ChatGPT for help? The command line is powerful, but its cryptic syntax can be a significant barrier to productivity.

Enter Neural Shell (nlsh) – an AI-driven command-line assistant that transforms natural language into shell commands tailored to your system context. It bridges the gap between what you want to do and the exact command syntax needed to do it.

The Problem: Command Line Friction

The command line interface (CLI) offers unparalleled power and flexibility for developers and system administrators. However, this power comes with a steep learning curve and cognitive overhead:

Syntax Complexity: Each shell has its own syntax quirks and command variations
Parameter Overload: Commands like find, awk, or sed have dozens of options and flags
Context Switching: Looking up commands interrupts your workflow and breaks concentration
System Differences: Commands that work on one OS or shell might fail on another (e.g., macOS vs. Linux)

These friction points slow us down and introduce opportunities for errors – some of which could be costly or dangerous when working with system commands.

How Neural Shell Solves These Problems

Neural Shell acts as a bridge between natural language and shell commands. Instead of remembering exact syntax, you describe what you want to accomplish right in your terminal, and nlsh generates the appropriate command:

# Instead of trying to remember the exact find syntax
nlsh find all log files larger than 10MB modified in the last week
# Suggested: find . -name "*.log" -size +10M -mtime -7
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
# (command output appears here)

The tool never executes commands automatically – it always shows you the suggested command and waits for your confirmation, allowing you to learn while using it.

Key Features That Make nlsh Special

🔄 Multi-Backend LLM Support

Neural Shell isn't tied to a single AI provider. It supports multiple OpenAI-compatible endpoints:

Local models via Ollama, LM Studio, etc., for privacy and offline use
Cloud providers like Groq, DeepSeek, and others
Easy switching between backends with simple flags (-0, -1, etc.)

This flexibility means you can use the model that best fits your needs, budget, and privacy requirements.

🧠 System-Aware Context

What sets nlsh apart from simply asking a general-purpose LLM (like ChatGPT) for shell commands is its system awareness. It automatically gathers information about your environment to generate more relevant commands.

Neural Shell uses a set of specialized system context tools to gather detailed information about your environment:

DirLister: Lists non-hidden files in the current directory with detailed metadata (file type, size, modification time). This helps the LLM understand what files are available in your working directory and their characteristics.
EnvInspector: Reports environment variables (with sensitive information automatically redacted) to ensure compatibility with your system. This includes shell information, PATH entries, and other important environment variables that might affect command execution.
SystemInfo: Provides comprehensive OS, kernel, and architecture context. This includes information about your operating system, version, distribution (for Linux), architecture, and Python environment, helping the LLM generate commands that are compatible with your specific system.

This context enables it to generate commands that are tailored to your specific environment without you having to manually provide this information.

🐚 Shell-Aware Generation

Different shells have different syntax requirements. Neural Shell respects this. If nlsh is configured for the fish shell (using the NLSH_SHELL environment variable or the shell setting in config.yml):

nlsh create a function that converts markdown to pdf
# Suggested: function md2pdf
#     pandoc $argv -o (basename $argv .md).pdf
# end
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
# Function 'md2pdf' defined

By configuring your preferred shell (bash/zsh/fish/powershell), nlsh ensures the commands it generates will work in your environment.

🛡️ Safety First Approach

Neural Shell prioritizes safety:

nlsh find all temporary files
# Suggested: find . -name "*.tmp" -type f
# [Confirm] Run this command? (y/N/e/r/x) x

# Explanation:
# ----------------------------------------
# This command finds all files with the .tmp extension in the current directory and subdirectories.
# - `find .` searches from the current directory
# - `-name "*.tmp"` matches files ending with .tmp
# - `-type f` ensures we only find regular files, not directories
# ----------------------------------------

The tool:

Never executes commands automatically.
Provides an explanation option ('x') to understand what a command does.
Allows editing commands before execution ('e').
Lets you regenerate suggestions if they don't match your intent ('r'). Each regeneration attempt also slightly increases the model's creativity (temperature) to encourage different suggestions.

It's worth noting that under the hood, nlsh uses subprocess.Popen with shell=True to execute commands, which is necessary for interpreting complex shell syntax. While this carries inherent risks if a malicious command were to be executed, the mandatory confirmation step serves as the primary safeguard. Always review suggested commands carefully before confirming execution.

Practical Use Cases

Daily File Management

nlsh find duplicate files in my downloads folder and show their sizes
# Suggested: find ~/Downloads -type f -exec md5sum {} \; | sort | uniq -w32 -d --all-repeated=separate | awk '{print $2}' | xargs du -sh
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
# 4.2M  ~/Downloads/report-v2.pdf
# 1.8M  ~/Downloads/presentation-draft.pptx
# (output truncated for brevity)

Complex Data Processing

nlsh extract all email addresses from log files and count unique domains
# Suggested: grep -Eo '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' *.log | awk -F@ '{print $2}' | sort | uniq -c | sort -nr
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
#      42 gmail.com
#      27 company.com
#      15 outlook.com
#       8 protonmail.com
# (output truncated for brevity)

System Administration

nlsh find processes using more than 1GB of memory
# Suggested: ps aux | awk '$6 > 1000000 {print $0}'
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
# user     12345 15.0  8.2 2145328 1345796 ?     Sl   10:23   2:14 /usr/lib/firefox/firefox
# user      9876  4.2  6.7 1782540 1098432 ?     Sl   09:45   1:32 /usr/bin/chromium-browser
# (output truncated for brevity)

Git Operations with nlgc

Neural Shell also includes a companion tool called nlgc (Neural Git Commit) that generates meaningful commit messages based on your staged changes:

# After staging changes
git add .

# Generate a commit message
nlgc
# Suggested commit message:
# --------------------
# feat: Add nlgc command for AI-generated commit messages
# 
# Implements the nlgc command which analyzes staged git diffs
# and uses an LLM to generate conventional commit messages.
# Includes configuration options and CLI flags to control
# whether full file content is included in the prompt.
# --------------------
# [Confirm] Use this message? (y/N/e/r) y
# Executing: git commit -m "feat: Add nlgc command..."
# Commit successful.

This helps maintain a clean, informative git history without the mental overhead of manually crafting the perfect commit message. nlgc also supports flags like --full-files / --no-full-files to control context size and -a / --all to consider all modified files, not just staged ones. Note that nlgc currently truncates individual files larger than ~100KB before adding them to the prompt to help prevent context overflows.

Getting Started

Installation is straightforward:

# Via pip
pip install neural-shell

# Or from source
git clone https://github.com/eqld/nlsh.git
cd nlsh
pip install .

Create a configuration file by copying the example:

mkdir -p ~/.nlsh
cp examples/config.yml ~/.nlsh/config.yml

Then, edit ~/.nlsh/config.yml to add your configuration. The config file has a simple structure:

shell: "zsh"  # Your preferred shell (bash/zsh/fish/powershell)
backends:
  - name: "local-ollama"
    url: "http://localhost:11434/v1"
    api_key: "ollama"
    model: "llama3"
  - name: "groq-cloud"
    url: "https://api.groq.com/v1"
    api_key: $GROQ_KEY
    model: "llama3-70b-8192"
default_backend: 0  # Index of the default backend to use

You'll need to add your API keys to the configuration. There are a few main ways to provide them:

In the config file: Paste the key directly or reference an environment variable using $VAR syntax (e.g., api_key: $MY_SECRET_KEY).
As environment variables: Set specific variables like OPENAI_API_KEY or NLSH_BACKEND_0_API_KEY. These override any keys specified in the config file.

For example, using the second method:

export OPENAI_API_KEY=sk-...

And you're ready to go!

Advanced Features

Command Interaction Features

Command Explanation

The 'x' option provides detailed explanations of suggested commands:

nlsh find all python files with TODO comments
# Suggested: grep -r "TODO" --include="*.py" .
# [Confirm] Run this command? (y/N/e/r/x) x

# Explanation:
# ----------------------------------------
# This command searches recursively for "TODO" in all Python files:
# - `grep -r` performs recursive searching
# - `"TODO"` is the text pattern to search for
# - `--include="*.py"` limits the search to Python files
# - `.` specifies to start the search from the current directory (`.` refers to the current directory)
# ----------------------------------------

This feature is invaluable for learning new commands and understanding complex one-liners.

Command Editing

The 'e' option allows you to edit a suggested command before execution, which is useful when you need to make small adjustments:

nlsh list files sorted by size
# Suggested: ls -lS
# [Confirm] Run this command? (y/N/e/r/x) e
# (Opens your $EDITOR with 'ls -lS')
# (Edit the command, e.g., to 'ls -lSh')
# Edited command: ls -lSh
# [Confirm] Run this command? (y/N/e/r/x) y

Command Regeneration

If you're not satisfied with a suggested command, you can ask for a different approach by responding with 'r':

nlsh find large files
# Suggested: find . -type f -size +100M
# [Confirm] Run this command? (y/N/e/r/x) r
# Regenerating command...
# Suggested: du -h -d 1 | sort -hr
# [Confirm] Run this command? (y/N/e/r/x) y

This tells the model to try a different approach. To encourage more diverse suggestions with each regeneration attempt, the temperature parameter (which controls randomness) is automatically increased by 0.1 for each regeneration, starting from 0.2 and capping at 1.0.

Command Fixing

Neural Shell can automatically fix failed commands by analyzing error output:

nlsh find files modified today
# Suggested: find . -mtime 0
# [Confirm] Run this command? (y/N/e/r/x) y
# Executing:
# find: unknown option -- m
# find: `find .mtime' is not a valid expression
# 
# ----------------
# Command execution failed with code 1
# Failed command: find . -mtime 0
# Try to fix? If you confirm, the command output and exit code will be sent to LLM.
# [Confirm] Try to fix this command? (y/N) y
# Fixing...
# Suggested: find . -type f -mtime 0
# [Confirm] Run this command? (y/N/e/r/x) y

This feature helps you quickly recover from command errors by analyzing the error output and exit code, considering your original intent, and generating a corrected version of the command.

Model and Prompt Features

Verbose Mode

For reasoning models, such as deepseek-reasoner, use the -v flag to see the AI's reasoning:

nlsh -v find large files consuming disk space
# Reasoning: To find large files consuming disk space, I'll use the 'find' command
# with size filtering, then sort the results by size using 'du'.
# Suggested: find . -type f -size +100M -exec du -h {} \; | sort -hr

This provides insight into how the AI approaches the problem. You can enable this feature by using models marked with is_reasoning_model: true in your config file and using the -v flag. For even more detail, use -vv to include debug information and stack traces if errors occur.

Custom Prompts

For more complex or repetitive tasks, you can provide a detailed prompt in a file using nlsh --prompt-file your_prompt.txt.

System and Logging Features

Improved Command Execution

Neural Shell executes commands using non-blocking I/O with the select module to read from stdout/stderr. This approach ensures compatibility with a wide range of commands, including those with pipes (|) and redirections. The non-blocking implementation prevents deadlocks that can occur with piped commands where one process might be waiting for input before producing output.

# Use select for non-blocking I/O
stdout_fd = process.stdout.fileno()
stderr_fd = process.stderr.fileno()

readable_fds = [stdout_fd, stderr_fd]
while readable_fds:
    # Use select to wait for data to be available
    ready_to_read, _, _ = select.select(readable_fds, [], [], 0.1)

    # Process has exited and no more data to read
    if not ready_to_read and process.poll() is not None:
        break

    for fd in ready_to_read:
        if fd == stdout_fd:
            data = process.stdout.read(1024)
            if not data:  # EOF
                readable_fds.remove(stdout_fd)
            else:
                safe_write(sys.stdout, data)
                stdout_data += data

This implementation ensures that output is displayed in real-time and prevents the command from hanging when dealing with complex pipelines.

Request Logging

For teams or audit purposes, you can log all requests:

nlsh --log-file ~/.nlsh/logs/requests.log find security vulnerabilities

The log file will contain JSON entries with timestamps, backend information, prompts, system context, and responses, which can be useful for debugging, auditing, or improving the tool's performance.

Note on Interactive Commands

While the select module implementation works well for most commands, highly interactive commands (like those with progress bars or TUI applications) might not render perfectly during execution via nlsh.

Why Neural Shell Matters

Neural Shell represents a shift in how we interact with command-line interfaces. Rather than forcing humans to think like computers, it allows computers to understand human intent.

The benefits include:

Reduced Context Switching: Stay in the flow without Googling commands
Faster Problem Solving: Convert intentions to actions immediately
Learning Opportunity: See, edit, explain, and understand the right commands for each task
Consistency: Generate commands that follow best practices
Safety: Review commands before execution to prevent mistakes

Conclusion

Neural Shell (nlsh) transforms the command-line experience from memorization to conversation. It maintains all the power and flexibility of the CLI while removing much of the friction.

Whether you're a seasoned sysadmin looking to save time, a developer wanting to stay in flow, or someone learning the command line, nlsh offers a more natural way to interact with your computer.

Give it a try and experience the future of command-line interfaces today!

Neural Shell is open source under the MIT license. Contributions are welcome at github.com/eqld/nlsh.

DEV Community: Evander Q. L. Darrow

Neural Shell (nlsh): Your AI-Powered Command Line Assistant