CommandRex 🦖

A natural language interface for terminal commands.

Description

CommandRex allows you to interact with your terminal using natural language. Simply tell CommandRex what you want to do, and it will translate your request into the appropriate terminal command. It's like having an AI assistant for your command line!

Features

Natural Language Command Translation: Convert plain English to precise terminal commands
Interactive Multi-Command Selection: Choose from multiple suggested commands using arrow keys in a simple table interface
Command Explanations: Get detailed explanations of what commands do and how they work
Safety Analysis: Automatic detection of potentially dangerous commands with warnings
Cross-Platform Support: Works on Windows, macOS, and Linux
Interactive Mode: Real-time command translation and execution with ASCII art welcome screen
Educational Breakdowns: Learn terminal commands through component-by-component explanations
Secure API Key Management: Your OpenAI API key is stored securely in your system's keyring

Requirements

Python 3.10 or higher
OpenAI API key (get one at https://platform.openai.com/api-keys)
Internet connection for API communication

Installation

From PyPI (Recommended)

pip install commandrex

From Source

git clone https://github.com/siddhantparadox/commandrex-cli.git
cd commandrex-cli
pip install -e .

Using Poetry (for Development)

Prerequisites: Poetry must be installed first. Install Poetry using one of these methods:

Linux/macOS/WSL:

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Alternative (using pipx):

pipx install poetry

Then install CommandRex:

git clone https://github.com/siddhantparadox/commandrex-cli.git
cd commandrex-cli
poetry install

Note: Poetry is a build and dependency management tool, not a runtime dependency. It should be installed separately on your system before using poetry install.

Python Version Compatibility

CommandRex supports Python 3.10 and above with no upper version limit:

Minimum Version: Python 3.10
Tested Versions: Python 3.10, 3.11, 3.12, 3.13
Future Compatibility: No upper bound - works with future Python releases

The project uses modern Python features available in 3.10+ and follows semantic versioning for dependency management.

Usage

CommandRex can be invoked using either commandrex or python -m commandrex followed by a command (run, translate, explain) and options.

For example:

commandrex run - Start interactive mode with multi-command selection
commandrex translate "query" - Translate a natural language query
commandrex translate "query" --no-strict-validation - Translate without strict env validation (per-invocation)
commandrex explain "command" - Explain a shell command

Interactive Mode

Start the interactive terminal interface:

commandrex run

This launches CommandRex in interactive mode with a welcome screen displaying "COMMAND REX" in green ASCII art. You can type natural language requests and get immediate command translations.

New in Interactive Mode: CommandRex now presents multiple command options by default. When you enter a query, you'll see a table with suggested commands and their explanations. Use arrow keys (↑/↓) to navigate and Enter to select. Press 'q' or ESC to cancel.

Options:

--debug or -d: Enable debug mode with detailed system information
--no-strict-validation: Disable strict environment validation for this run/translation
--api-key YOUR_KEY: Use a specific OpenAI API key for this session
--model MODEL_NAME: Specify an OpenAI model (default: gpt-5-mini-2025-08-07)
--translate "query" or -t "query": Directly translate a query without entering interactive mode

Example:

commandrex run --model gpt-5-mini-2025-08-07 --debug

Command Translation

Translate natural language to a shell command:

commandrex translate "list all files in the current directory including hidden ones"

Options:

--execute or -e: Execute the translated command after showing it
--multi-select: Present multiple command options to choose from interactively
--api-key YOUR_KEY: Use a specific OpenAI API key for this translation
--model MODEL_NAME: Specify an OpenAI model (default: gpt-5-mini-2025-08-07)
--no-strict-validation: Disable strict validation for this translation (shows guidance instead of blocking)

Examples:

commandrex translate "find all PDF files modified in the last week"
commandrex translate "create a backup of my Documents folder" --execute
commandrex translate "show me all files" --multi-select

Multi-Command Selection

CommandRex can suggest multiple command options for your query:

In interactive mode (default behavior):

commandrex run
> show me all files

In translate mode (opt-in with flag):

commandrex translate "show me all files" --multi-select

The selection interface shows:

A simple table with "Command" and "Explanation" columns
Navigation with Up/Down arrow keys
Enter to select a command
'q' or ESC to cancel

After selection, CommandRex displays the standard output with:

The selected command
Full explanation
Component breakdown showing what each part does
Safety assessment if applicable

Command Explanation

Get a detailed explanation of a shell command:

commandrex explain "grep -r 'TODO' --include='*.py' ."

This will provide:

A general explanation of what the command does
Breakdown of each component
Safety assessment
Related commands and examples

Options:

--api-key YOUR_KEY: Use a specific OpenAI API key for this explanation
--model MODEL_NAME: Specify an OpenAI model (default: gpt-5-mini-2025-08-07)

Help System

CommandRex features a comprehensive help system with beautiful formatting:

Main Help:

commandrex --help

Shows a beautifully formatted overview with:

Available commands in a table
Global options in a styled box
Usage examples with syntax highlighting
Troubleshooting section with common solutions

Command-Specific Help:

commandrex run --help        # Interactive mode help
commandrex translate --help  # Translation command help
commandrex explain --help    # Explanation command help

Each command provides detailed information about its options and usage patterns.

Global Options

These options work with any command:

--version or -v: Show the application version
--reset-api-key: Reset the stored OpenAI API key

Examples:

commandrex --version
commandrex --reset-api-key

First-Time Setup

When you first run CommandRex, it will:

Ask for your OpenAI API key (get one at https://platform.openai.com/api-keys)
Store this key securely in your system's keyring
Detect your shell environment and operating system

The API key setup only happens once; the key is stored securely for future use.

Example Workflow

Basic Translation:

# Translate a natural language query to a command
commandrex translate "find large files in my Downloads folder"

Translation with Multi-Select:

# Get multiple options and choose interactively
commandrex translate "show system information" --multi-select

Interactive Mode:

# Start interactive mode
commandrex run

# In interactive mode:
# 1. Welcome screen displays "COMMAND REX" in green ASCII art
# 2. Type your request and press Enter
# 3. See multiple command options in a table
# 4. Use arrow keys to select the best option
# 5. See the translation and explanation
# 6. Choose whether to execute it
# 7. Type 'exit' or press Ctrl+C to quit

Troubleshooting

API Key Issues:

# Reset your API key
commandrex --reset-api-key

Command Accuracy: If a translated command doesn't match your intent:

Try being more specific in your request
Use the multi-select feature to see alternative options
Use the interactive mode to refine your query
Try a different model with --model gpt-5-mini-2025-08-07 for potentially better results

Shell Detection:

# Run in debug mode to see detected shell information
commandrex run --debug

Examples

Here are some examples of natural language queries you can use with CommandRex:

"Show me all running processes"
"Find all text files containing the word 'important'"
"Create a backup of my documents folder"
"Show disk usage for the current directory"
"Kill the process running on port 3000"
"Extract the contents of archive.zip to the folder 'extracted'"
"Show me the last 50 lines of the error log"

How It Works

CommandRex uses OpenAI's language models to translate your natural language requests into terminal commands. It provides context about your operating system, shell environment, and common command patterns to generate accurate and safe commands.

The application:

Analyzes your request
Generates multiple appropriate command options (in interactive mode)
Lets you select the best option using arrow keys
Explains what the command does
Checks for potential safety issues
Executes the command if requested

Security

CommandRex takes security seriously:

Your API key is stored securely in your system's keyring
Commands are analyzed for potential security risks before execution
Potentially dangerous commands are clearly marked with warnings
You always have the final say on whether to execute a command
No data is stored or shared beyond what's needed for API communication

Testing

CommandRex has a comprehensive test suite with 522 tests achieving 86.89% code coverage. The project follows Test-Driven Development (TDD) practices to ensure code quality and reliability.

Running Tests

Run all tests:

# Using pytest directly
pytest

# With coverage report
pytest --cov=commandrex --cov-report=term-missing

# Using the test runner script
python run_tests.py

Run specific test categories:

# Unit tests only
pytest tests/unit/

# Integration tests only
pytest tests/integration/

# End-to-end tests only
pytest tests/e2e/

# Run tests in parallel (faster)
pytest -n auto

Run specific test files:

# Test a specific module
pytest tests/unit/test_security.py

# Test with verbose output
pytest tests/unit/test_api_manager.py -v

# Run a specific test
pytest tests/unit/test_security.py::TestCommandSafetyAnalyzer::test_analyze_command_dangerous_rm_rf

Test Structure

The test suite is organized into three main categories:

tests/
├── conftest.py              # Shared test fixtures and configuration
├── unit/                    # Unit tests (488 tests)
│   ├── test_api_manager.py  # API key management tests
│   ├── test_security.py     # Security and safety analysis tests
│   ├── test_main.py         # CLI interface tests
│   ├── test_openai_client.py # OpenAI API integration tests
│   └── ...
├── integration/             # Integration tests (9 tests)
│   └── test_basic_workflow.py # Cross-component workflow tests
└── e2e/                     # End-to-end tests (25 tests)
    └── test_cli_commands.py # Complete CLI command testing

Test Coverage

Current test coverage by module:

API Manager: 100% coverage
Security Module: 99% coverage
Settings Module: 99% coverage
Shell Manager: 100% coverage
OpenAI Client: 100% coverage
Prompt Builder: 100% coverage
Logging Utils: 100% coverage
Command Parser: 91% coverage
Platform Utils: 78% coverage
Main CLI: 68% coverage

Development Testing

Prerequisites for testing:

# Install development dependencies
pip install -e ".[dev]"

# Or using Poetry
poetry install

Test configuration:

Minimum coverage threshold: 80%
Test timeout: 300 seconds
Parallel execution supported
Cross-platform testing (Windows, macOS, Linux)

Continuous Integration: Tests run automatically on:

Pull requests
Pushes to main branch
Multiple Python versions (3.10, 3.11, 3.12)
Multiple operating systems

Writing Tests: See TDD_WORKFLOW.md for detailed guidelines on:

Test-driven development practices
Writing effective unit tests
Mocking strategies for external dependencies
Integration testing patterns
End-to-end testing approaches

Test Utilities:

Fixtures: Shared test data and mock objects in conftest.py
Mocking: Comprehensive mocking of OpenAI API, file system, and system calls
Async Testing: Full support for testing async/await code patterns
CLI Testing: Specialized testing for Typer-based CLI commands

Code Quality and Pre-commit Hooks

CommandRex uses pre-commit hooks to maintain code quality and consistency. The project includes automated formatting, linting, and various file checks.

Setting up Pre-commit

Install development dependencies:

# Using pip
pip install -e ".[dev]"

# Or using Poetry
poetry install --with dev

Install pre-commit hooks:

pre-commit install

Pre-commit Hooks

The following hooks run automatically on every commit:

Ruff v0.12.4: Extremely fast Python linting and formatting (with unsafe fixes enabled)
Trailing whitespace: Removes trailing whitespace
End of file fixer: Ensures files end with a newline
Merge conflict checker: Detects merge conflict markers
YAML syntax checker: Validates YAML files
TOML syntax checker: Validates TOML files
Large file checker: Prevents committing large files (max 1MB)

Note: This project uses Ruff exclusively for both linting and formatting, eliminating the need for separate Black and isort tools. Ruff provides equivalent functionality with superior performance.

All Python-related hooks are optimized to run only on Python files (.py, .pyi) for better performance.

Manual Hook Execution

Run all hooks on all files:

pre-commit run --all-files

Run specific hooks:

# Run only ruff linting
pre-commit run ruff-check --all-files

# Run only ruff formatting
pre-commit run ruff-format --all-files

# Run only trailing whitespace fixer
pre-commit run trailing-whitespace --all-files

# Run only YAML checker
pre-commit run check-yaml --all-files

# Run only TOML checker
pre-commit run check-toml --all-files

Update hook versions:

pre-commit autoupdate

Editor Integration with Ruff Server

For the best development experience, configure your editor to use the native Ruff language server instead of the older ruff-lsp. The native server offers superior performance and is built directly into Ruff.

VS Code Setup: Add this to your VS Code settings (.vscode/settings.json or user settings):

{
    "ruff.nativeServer": "on",
    "ruff.fixAll": true,
    "ruff.organizeImports": true,
    "ruff.showSyntaxErrors": true
}

Neovim Setup (0.11+):

vim.lsp.config('ruff', {
  init_options = {
    settings = {
      fixAll = true,
      organizeImports = true,
      showSyntaxErrors = true
    }
  }
})
vim.lsp.enable('ruff')

Neovim Setup (0.10 with nvim-lspconfig):

require('lspconfig').ruff.setup({
  init_options = {
    settings = {
      fixAll = true,
      organizeImports = true,
      showSyntaxErrors = true
    }
  }
})

Other Editors: Most editors support the Language Server Protocol. Configure your editor to use:

Command: ruff server
File types: Python (.py, .pyi)

Benefits of Native Ruff Server:

Superior Performance: Native Rust implementation is significantly faster than ruff-lsp
Built-in: No separate installation required
Modern Architecture: Lock-free data model with continuous event loop
Better Integration: More reliable LSP implementation with real-time diagnostics

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup:

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/commandrex-cli.git
Install development dependencies: pip install -e ".[dev]"
Install pre-commit hooks: pre-commit install
Run tests to ensure everything works: pytest
Make your changes following TDD practices
Ensure tests pass and coverage remains above 80%
Submit a pull request

Code Quality Requirements:

All commits must pass pre-commit hooks (ruff, trailing whitespace, etc.)
All new code must have corresponding tests
Maintain or improve test coverage
Follow existing test patterns and conventions
Include both unit and integration tests where appropriate

CI/CD Integration: Pre-commit hooks should also be integrated into your CI/CD pipeline to ensure code quality standards are maintained across all contributions. Consider adding a workflow step that runs pre-commit run --all-files in your GitHub Actions or other CI systems.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github/workflows		.github/workflows
commandrex		commandrex
docs		docs
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
README.md		README.md
TDD_WORKFLOW.md		TDD_WORKFLOW.md
TESTING.md		TESTING.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
run_tests.py		run_tests.py

siddhantparadox/commandrex-cli

Folders and files

Latest commit

History

Repository files navigation

CommandRex 🦖

Description

Features

Requirements

Installation

From PyPI (Recommended)

From Source

Using Poetry (for Development)

Python Version Compatibility

Usage

Interactive Mode

Command Translation

Multi-Command Selection

Command Explanation

Help System

Global Options

First-Time Setup

Example Workflow

Troubleshooting

Examples

How It Works

Security

Testing

Running Tests

Test Structure

Test Coverage

Development Testing

Code Quality and Pre-commit Hooks

Setting up Pre-commit

Pre-commit Hooks

Manual Hook Execution

Editor Integration with Ruff Server

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages