py-ai-shell

AI-powered shell assistant that generates and explains shell commands based on natural language prompts.

py-ai-shell transforms your natural language descriptions into shell commands, explains what they do, and helps you fix errors. It's like having a shell expert by your side, making command-line work more accessible and efficient.

Installation

pip install py-ai-shell

Requirements:

• Python 3.8 or higher
• OpenAI API key

py-ai-shell works on Linux, macOS, and Windows with support for bash, zsh, fish, and PowerShell.

Quick Start

Basic Usage

# Start py-ai-shell interactive mode
ai

# Run with a one-time prompt
ai "list all files in the current directory"

# Configure py-ai-shell
ai config set OPENAI_KEY=your_api_key

When you run a command, py-ai-shell will:

1. Generate the appropriate shell command
2. Show you what it's going to do
3. Execute the command when you approve
4. Provide explanations and error analysis if needed

Features

• Natural Language Command Generation: Convert plain English to shell commands
• Command Explanations: Understand what commands do before running them
• Error Analysis: Get explanations and suggestions when commands fail
• Command History: py-ai-shell remembers context from previous commands
• Multiple Shell Support: Works with bash, zsh, fish, and PowerShell
• Interactive Mode: Full interactive shell experience
• One-off Mode: Quick command generation without entering interactive mode
• Configurable: Use different OpenAI models and customize behavior
• Copy to Clipboard: Easily copy generated commands
• Silent Mode: Less verbose output for experienced users

Configuration

py-ai-shell can be configured using the config command:

# Set your OpenAI API key
ai config set OPENAI_KEY=your_api_key

# Set the model to use (default: gpt-4.1-nano)
ai config set MODEL=gpt-4.1-nano

# Enable silent mode (less verbose output)
ai config set SILENT_MODE=true

# Set API endpoint (useful for proxies or alternative providers)
ai config set OPENAI_API_ENDPOINT=https://api.openai.com/v1

# Set language (default: en)
ai config set LANGUAGE=en

Configuration is stored in ~/.config/py-ai-shell/config.ini and can be edited directly.

Advanced Usage

Command Options

# Run in silent mode (less verbose output)
ai -s "list files by size"

# Provide a custom prompt
ai -p "show disk usage"

Error Analysis

When a command fails, py-ai-shell can analyze the error and suggest fixes:

$ ai "find files modified in the last 24 hours"
# If the command fails, py-ai-shell will offer to analyze the error
Command failed. Would you like an explanation? (?/??/???)

Enter ? for a brief explanation, ?? for a standard explanation, or ??? for a detailed analysis.

Command History

py-ai-shell maintains a history of your recent commands and their results, providing context for future commands. This helps the AI understand your environment and previous actions.

Interactive Options

After a command is generated, you'll see options:

• a/A: Accept and run the command
• e/E: Edit the command before running
• r/R: Revise (ask AI to generate a new command)
• c/C: Copy the command to clipboard
• s/S: Stick to your original command
• q/Q: Quit/cancel

Using with Different Shells

py-ai-shell automatically detects your current shell, but you can generate commands for specific shells by mentioning them in your prompt:

ai "list all processes in PowerShell syntax"

Development

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/cheney-yan/py-ai-shell.git
   cd py-ai-shell
   

2. Install development dependencies:

   make dev
   

Available Make Commands

• make help: Show available commands
• make clean: Remove all build, test, coverage and Python artifacts
• make lint: Check style with flake8
• make test: Run tests
• make coverage: Check code coverage
• make dist: Package for distribution
• make install: Install the package locally
• make dev: Install development dependencies

Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure your code passes all tests and linting checks before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• This project is inspired by the AI Shell project
• Built with OpenAI API
• Command-line interface powered by Click
• Terminal styling with Rich