{"id":13910474,"url":"https://github.com/theghostrat/NaturalShell","last_synced_at":"2025-07-18T09:31:37.190Z","repository":{"id":229355064,"uuid":"776509663","full_name":"theghostrat/NaturalShell","owner":"theghostrat","description":"NaturalShell, an AI-driven command-line tool, effortlessly translates natural language into shell commands. Say goodbye to complex syntax and hello to intuitive interaction with your system.","archived":false,"fork":false,"pushed_at":"2024-05-12T06:22:08.000Z","size":52,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-27T00:55:08.468Z","etag":null,"topics":["ai","automation","bash","cmd","langchain","linux","llm","openai","powershell","shell"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theghostrat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-23T17:52:57.000Z","updated_at":"2024-09-24T16:51:57.000Z","dependencies_parsed_at":"2024-03-23T19:29:36.761Z","dependency_job_id":"316ce5e7-e7e5-4213-85ac-e57d64421f3e","html_url":"https://github.com/theghostrat/NaturalShell","commit_stats":null,"previous_names":["theghostrat/naturalshell"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/theghostrat/NaturalShell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theghostrat%2FNaturalShell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theghostrat%2FNaturalShell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theghostrat%2FNaturalShell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theghostrat%2FNaturalShell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theghostrat","download_url":"https://codeload.github.com/theghostrat/NaturalShell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theghostrat%2FNaturalShell/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265733911,"owners_count":23819437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","bash","cmd","langchain","linux","llm","openai","powershell","shell"],"created_at":"2024-08-07T00:01:27.854Z","updated_at":"2025-07-18T09:31:36.905Z","avatar_url":"https://github.com/theghostrat.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\n# NaturalShell 🐚✨\n\nNaturalShell 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.\n\n![Demo](https://user-images.githubusercontent.com/your_username/natural-shell/assets/demo.gif)\n\n## Features ✨\n\n- **Natural Language Processing**: NaturalShell employs cutting-edge language models to comprehend your natural language input and translate it into executable shell commands.\n- **Multi-Model Support**: Choose from Google GenerativeAI, OpenAI, or Anthropic language models to align with your requirements.\n- **Flexible Execution**: Effortlessly fetch, print, or execute commands directly from your terminal using intuitive subcommands or within your Python scripts.\n- **Customizable Configuration**: Tailor your API keys and language model preferences conveniently within a centralized `config.yaml` file or directly through your code.\n- **Easy Installation**: Install NaturalShell swiftly with a few commands and kickstart your journey immediately.\n\n## Installation 🚀\n\nYou can install NaturalShell via pip:\n\n```bash\npip install natural-shell\n```\n### Or\n\nTo install NaturalShell directly from its GitHub repository using pip, you can use the following command:\n\n```bash\npip install git+https://github.com/theghostrat/NaturalShell.git\n```\n\nThis command will clone the repository and install the package along with its dependencies.\n\nAlternatively, 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:\n\n```bash\npip install -e git+https://github.com/theghostrat/NaturalShell.git\n```\n\nThis will install NaturalShell in editable mode, and any changes you make to the code will be reflected without needing to reinstall the package.\n\nBoth of these commands will fetch the latest version of NaturalShell from its GitHub repository and install it on your system.\n\n### Manual Installation\n\nNaturalShell isn't available on PyPI yet, but fret not, you can install it directly from the GitHub repository:\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/theghostrat/NaturalShell.git\n```\n\n2. Navigate to the project directory:\n\n```bash\ncd natural-shell\n```\n\n3. Install the package and its dependencies:\n\n```bash\npip install .\n```\n\n## Configuration\n\nNaturalShell provides two ways to configure the library: through a `config.yaml` file or directly within your Python code.\n\n### Configuration via `config.yaml`\n\nNaturalShell uses environment variables for configuration. You can set the following environment variable to customize its behavior:\n\n- `NSHELL_CONFIG`: Path to the configuration file (default: `config.yaml` in the current directory).\n\nFor example, to specify a custom configuration file located at `/path/to/custom/config.yaml`, you can set the `NSHELL_CONFIG` environment variable as follows:\n\n```bash\nexport NSHELL_CONFIG=/path/to/custom/config.yaml\n```\n\n1. Create a `config.yaml` file in the directory where you plan to use NaturalShell.\n\n2. Open the `config.yaml` file in a text editor.\n\n3. Add the following content to the `config.yaml` file:\n\n```yaml\napi_key: YOUR_API_KEY\nmodel: google-genai or openai,etc\nbase_url: https://api.example.com/v1\n```\n\nReplace `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.\n\n### Configuration via Code\n\nYou can also configure NaturalShell directly within your Python code by modifying the properties of the `LanguageModel` instance:\n\n```python\nfrom natural_shell import LanguageModel\n\n# Create the LanguageModel instance\nllm_instance = LanguageModel()\n\n# Set custom configuration\nllm_instance.api_key = 'your_api_key'\nllm_instance.model = 'openai'\nllm_instance.base_url = 'https://api.example.com/v1'\n\n# Get the language model instance\nlanguage_model = llm_instance.get_language_model()\n```\n\n## Usage 🤖\n\nNaturalShell provides two main functions: `fetch_command` and `execute_command`. You can use these functions either from the command line or within your Python scripts.\n\n### Command-Line Usage\n\nPost-installation, commence your NaturalShell experience right from your terminal or command prompt:\n\n```bash\n# Print the shell command\nnshell \"list all files in the current directory\" print\n\n# Execute the shell command\nnshell \"list all files in the current directory\" exec\n```\n\n### Python Script Usage\n\nYou can also import and use the `fetch_command` and `execute_command` functions from your Python scripts:\n\n```python\nfrom natural_shell import fetch_command, execute_command, LanguageModel\n\n# Create the LanguageModel instance\nllm_instance = LanguageModel()\n\n# Set custom configuration (optional)\nllm_instance.api_key = 'your_api_key'\nllm_instance.model = 'openai'\nllm_instance.base_url = 'https://api.example.com/v1'\n\n# Get the language model instance\nlanguage_model = llm_instance.get_language_model()\n\n# Fetch the command without executing it\ncommand = fetch_command(\"list all files in the current directory\", language_model)\nprint(\"Command:\", command)\n\n# Execute the command and get the output\ncommand, output = execute_command(\"list all files in the current directory\", language_model)\nprint(\"Command:\", command)\nprint(\"Output:\", output)\n```\n\nIn this example:\n\n1. We import the necessary functions and classes from `natural_shell`.\n2. We create an instance of the `LanguageModel` class.\n3. (Optional) We set the custom configuration by modifying the properties of the `LanguageModel` instance.\n4. We obtain the language model instance using the `get_language_model` method.\n5. We use the `fetch_command` function to get the shell command as a string without executing it.\n6. We use the `execute_command` function to execute the command and get the output.\n\nBy 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.\n\n## Contributing 🤝\n\nCommunity contributions are highly valued! If you're inclined to enhance NaturalShell, follow these steps:\n\n1. Fork the repository\n2. Create a new branch (`git checkout -b feature/your-feature-name`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin feature/your-feature-name`)\n5. Open a Pull Request\n\n## License 📄\n\nNaturalShell operates under the [MIT License](https://opensource.org/licenses/MIT).\n\n## Acknowledgments 🙏\n\nNaturalShell flourishes thanks to the remarkable contributions of the following open-source projects:\n\n- [LangChain](https://github.com/hwchase17/langchain)\n- [langchain-google-genai](https://github.com/hwchase17/langchain/tree/main/langchain/chains/llm)\n- [langchain-openai](https://github.com/hwchase17/langchain/tree/main/langchain/llms/openai)\n- [langchain-anthropic](https://github.com/hwchase17/langchain/tree/main/langchain/llms/anthropic)\n\nWe extend our gratitude to our phenomenal contributors and the vibrant open-source community for their invaluable support and contributions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheghostrat%2FNaturalShell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheghostrat%2FNaturalShell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheghostrat%2FNaturalShell/lists"}