A tool for converting natural language to shell commands
Project description
NaturalShell 🐚✨
NaturalShell is an AI-driven command-line tool that effortlessly translates natural language into shell commands. Say goodbye to complex syntax and hello to intuitive interaction with your system.
Features ✨
- Natural Language Processing: NaturalShell employs cutting-edge language models to comprehend your natural language input and translate it into executable shell commands.
- Multi-Model Support: Choose from Google GenerativeAI, OpenAI, or Anthropic language models to align with your requirements.
- Flexible Execution: Effortlessly fetch, print, or execute commands directly from your terminal using intuitive subcommands or within your Python scripts.
- Customizable Configuration: Tailor your API keys and language model preferences conveniently within a centralized
config.yaml
file or directly through your code. - Easy Installation: Install NaturalShell swiftly with a few commands and kickstart your journey immediately.
Installation 🚀
To install NaturalShell directly from its GitHub repository using pip, you can use the following command:
pip install git+https://github.com/theghostrat/NaturalShell.git
This command will clone the repository and install the package along with its dependencies.
Alternatively, if you want to install it in editable mode, allowing you to make changes to the code and see the changes reflected immediately without reinstalling, you can use:
pip install -e git+https://github.com/theghostrat/NaturalShell.git
This will install NaturalShell in editable mode, and any changes you make to the code will be reflected without needing to reinstall the package.
Both of these commands will fetch the latest version of NaturalShell from its GitHub repository and install it on your system.
Manual Installation
NaturalShell isn't available on PyPI yet, but fret not, you can install it directly from the GitHub repository:
- Clone the repository:
git clone https://github.com/theghostrat/NaturalShell.git
- Navigate to the project directory:
cd natural-shell
- Install the package and its dependencies:
pip install .
Configuration
NaturalShell provides two ways to configure the library: through a config.yaml
file or directly within your Python code.
Configuration via config.yaml
NaturalShell uses environment variables for configuration. You can set the following environment variable to customize its behavior:
NSHELL_CONFIG
: Path to the configuration file (default:config.yaml
in the current directory).
For example, to specify a custom configuration file located at /path/to/custom/config.yaml
, you can set the NSHELL_CONFIG
environment variable as follows:
export NSHELL_CONFIG=/path/to/custom/config.yaml
-
Create a
config.yaml
file in the directory where you plan to use NaturalShell. -
Open the
config.yaml
file in a text editor. -
Add the following content to the
config.yaml
file:
api_key: YOUR_API_KEY
model: google-genai or openai,etc
base_url: https://api.example.com/v1
Replace YOUR_API_KEY
with your actual API key. You can choose the language model by setting the model
field to one of the following options: google-genai
, openai
, or anthropic
. If you're using a custom API endpoint for OpenAI, you can specify it in the base_url
field.
Configuration via Code
You can also configure NaturalShell directly within your Python code by modifying the properties of the LanguageModel
instance:
from natural_shell import LanguageModel
# Create the LanguageModel instance
llm_instance = LanguageModel()
# Set custom configuration
llm_instance.api_key = 'your_api_key'
llm_instance.model = 'openai'
llm_instance.base_url = 'https://api.example.com/v1'
# Get the language model instance
language_model = llm_instance.get_language_model()
Usage 🤖
NaturalShell provides two main functions: fetch_command
and execute_command
. You can use these functions either from the command line or within your Python scripts.
Command-Line Usage
Post-installation, commence your NaturalShell experience right from your terminal or command prompt:
# Print the shell command
nshell "list all files in the current directory" print
# Execute the shell command
nshell "list all files in the current directory" exec
Python Script Usage
You can also import and use the fetch_command
and execute_command
functions from your Python scripts:
from natural_shell import fetch_command, execute_command, LanguageModel
# Create the LanguageModel instance
llm_instance = LanguageModel()
# Set custom configuration (optional)
llm_instance.api_key = 'your_api_key'
llm_instance.model = 'openai'
llm_instance.base_url = 'https://api.example.com/v1'
# Get the language model instance
language_model = llm_instance.get_language_model()
# Fetch the command without executing it
command = fetch_command("list all files in the current directory", language_model)
print("Command:", command)
# Execute the command and get the output
command, output = execute_command("list all files in the current directory", language_model)
print("Command:", command)
print("Output:", output)
In this example:
- We import the necessary functions and classes from
natural_shell
. - We create an instance of the
LanguageModel
class. - (Optional) We set the custom configuration by modifying the properties of the
LanguageModel
instance. - We obtain the language model instance using the
get_language_model
method. - We use the
fetch_command
function to get the shell command as a string without executing it. - We use the
execute_command
function to execute the command and get the output.
By separating the command fetching and execution, you have the flexibility to handle the generated command as per your needs, whether it's executing it directly or using it in your own code.
Contributing 🤝
Community contributions are highly valued! If you're inclined to enhance NaturalShell, follow these steps:
- Fork the repository
- Create a new branch (
git checkout -b feature/your-feature-name
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin feature/your-feature-name
) - Open a Pull Request
License 📄
NaturalShell operates under the MIT License.
Acknowledgments 🙏
NaturalShell flourishes thanks to the remarkable contributions of the following open-source projects:
We extend our gratitude to our phenomenal contributors and the vibrant open-source community for their invaluable support and contributions.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for natural_shell-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e7961bc043654b516182445a2b7e7cacd779a50adf0fc3b80412508e76a8f78f |
|
MD5 | 5403af944d0e3713f0c1718c29f6612a |
|
BLAKE2b-256 | d47def2b6cf9ee47ed619c88e4213ac2f0ef40077b608fa432e939c24b16a14c |