From 574499886defedc2a5077aff6be480550eb9928c Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Sun, 31 Dec 2023 14:17:58 -0600 Subject: [PATCH 1/6] Update readme --- README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 109 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7fc39bf..921888f 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,115 @@ -# ShellOracle +# ShellOracle -More exciting stuff coming soon so ⭐ and 👀️ to stay in the loop. +ShellOracle is a terminal utility for intelligent shell command generation. ![ShellOracle](https://i.imgur.com/QM2LkAf.gif) -# Installation +More exciting stuff coming soon so ⭐ and 👀️ to stay in the loop. + +## Table of Contents + +- [Introduction](#introduction) +- [Features](#features) +- [Installation](#installation) +- [Usage](#usage) +- [Configuration](#configuration) +- [Feedback](#feedback) + +## Introduction + +ShellOracle is a terminal utility allows you to generate shell commands from a written description. + +## Features + +A few of the key features of ShellOracle: + +* Generate shell commands from written description with ease +* Command history +* Unix pipe support +* Self-hosted +* Fully configurable + +## Installation + +To install ShellOracle, download and run the installer python zip application with the following one-liner: +```zsh +curl -sSL https://raw.githubusercontent.com/djcopley/ShellOracle/master/installer.pyz -o /tmp/installer.pyz && python3 /tmp/installer.pyz +``` + +> [!NOTE] +> ShellOracle uses Ollama as its default LLM provider. Follow the installation instructions [here](https://ollama.ai/). + +## Usage + +ShellOracle is primarily intended to be used as a ZSH Line Editor widget activated by the CTRL+F keyboard shortcut. + +1. Press CTRL+F +2. Describe your command or goal +3. Press enter + +The generated command will be inserted into your shell prompt after a few seconds! + +#### Ollama + +Before running ShellOracle with Ollama, you must first pull the model you want to use. By default, ShellOracle uses the +`codellama:13b model`. To pull the default model run: + +```zsh +ollama pull codellama:13b +``` + +#### OpenAI + +To run ShellOracle with the OpenAI provider, you must first create an +[API key](https://platform.openai.com/account/api-keys). Edit your ~/.shelloracle/config.toml to change your provider +and enter your API key. + +#### Tips + +1. If you hit CTRL+F with text already in your ZLE buffer, all the text left of your cursor will be carried over to your ShellOracle prompt +2. UP_ARROW and DOWN_ARROW will cycle through your prompt history +3. ShellOracle can be chained together with other commands; try: `echo "find all the python files in my cwd" | shor` + +#### Other ways to run ShellOracle + +ShellOracle can also be run as a python module, with `python3 -m shelloracle`, or with its entrypoint `shor`. + +> [!NOTE] +> You must add your `~/.local/bin` directory to your [PATH]() for the entrypoint to work. Additionally, running +> ShellOracle with this method will not automatically insert the result into your shell prompt, so you'll have to +> copy and paste. + +## System Requirements + +If you are using a cloud provider like OpenAI, there are no system requirements. + +If you are self-hosting, system requirements vary depending on the model you are running. The Ollama model registry +has more information about + +## Configuration + +ShellOracle configuration is handled by the ~/.shelloracle/config.toml file. The configuration looks like this: + +```toml +[shelloracle] +# Shell oracle configuration settings +provider = "Ollama" + +[provider.Ollama] +# Provider settings +model = "codellama:13b" + +[provider.OpenAI] +api_key = "" +model = "gpt-3.5-turbo" +``` + +Setting the `provider` key lets ShellOracle know what LLM backend to use. Currently, the options for this field are +"Ollama" and "OpenAI". + +Provider specific configuration is handled through the `[Provider.NAME]` tags. -1. Install [Ollama](https://ollama.ai/) -2. Install shelloracle - ```zsh - curl -sSL https://raw.githubusercontent.com/djcopley/ShellOracle/master/installer.pyz -o /tmp/installer.pyz && python3 /tmp/installer.pyz - ``` -3. Use ctrl+f to open the prompt +## Contributing +If you run into any problems, feel free to [file an issue](https://github.com/djcopley/ShellOracle/issues/new). +Feature requests are always welcome. If you wish to contribute, open a pull-request. From 3886bce7313fd7356bc01bc1eb991a805b275e84 Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Tue, 2 Jan 2024 13:10:07 -0500 Subject: [PATCH 2/6] Revision 1 --- README.md | 125 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 85 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 921888f..73bcf5e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # ShellOracle -ShellOracle is a terminal utility for intelligent shell command generation. +ShellOracle is an innovative terminal utility designed for intelligent shell command generation, bringing a new level of +efficiency to your command-line interactions. ![ShellOracle](https://i.imgur.com/QM2LkAf.gif) -More exciting stuff coming soon so ⭐ and 👀️ to stay in the loop. +Explore our dynamic features and look forward to more exciting updates by giving us a ⭐ and a 👀 ## Table of Contents @@ -17,42 +18,65 @@ More exciting stuff coming soon so ⭐ and 👀️ to stay in the loop. ## Introduction -ShellOracle is a terminal utility allows you to generate shell commands from a written description. +In the ever-evolving landscape of command-line interfaces, ShellOracle emerges as a game-changer. This terminal utility +empowers users to effortlessly generate shell commands by simply describing their intentions. Whether you're a seasoned +developer or a command-line enthusiast, ShellOracle streamlines your workflow, making complex command creation an +intuitive and accessible process. + +**Why ShellOracle?** + +- **Intelligence at Your Fingertips:** No need to memorize intricate shell commands. Describe your task, and let + ShellOracle intelligently generate the command for you. + +- **Enhanced Productivity:** Say goodbye to manual command crafting. With ShellOracle, you can save time and focus on + what matters by leveraging the power of natural language descriptions. + +- **Versatile Integration:** Whether you're working on a quick one-liner or chaining multiple commands, ShellOracle + adapts to your needs. Enjoy the flexibility of Unix pipe support and command history. + +- **Self-hosted Control:** Take charge of your environment by running ShellOracle as a self-hosted utility. Full control + means you tailor it to your preferences. + +This is more than just a utility; it's a tool that transforms how you interact with the command line. With ShellOracle, +the language of the shell becomes more accessible, intuitive, and efficient. ## Features -A few of the key features of ShellOracle: +Key features of ShellOracle include: -* Generate shell commands from written description with ease -* Command history -* Unix pipe support -* Self-hosted -* Fully configurable +* Seamless shell command generation from written descriptions +* Command history for easy reference +* Unix pipe support for advanced command chaining +* Self-hosted for full control over your environment +* Highly configurable to adapt to your preferences ## Installation -To install ShellOracle, download and run the installer python zip application with the following one-liner: +To experience the power of ShellOracle, use the following one-liner to download and run the installer Python zip +application: + ```zsh curl -sSL https://raw.githubusercontent.com/djcopley/ShellOracle/master/installer.pyz -o /tmp/installer.pyz && python3 /tmp/installer.pyz ``` > [!NOTE] -> ShellOracle uses Ollama as its default LLM provider. Follow the installation instructions [here](https://ollama.ai/). +> ShellOracle uses Ollama as its default Language Model (LLM) provider. Follow the installation +> instructions [here](https://ollama.ai/). ## Usage -ShellOracle is primarily intended to be used as a ZSH Line Editor widget activated by the CTRL+F keyboard shortcut. +ShellOracle is designed to be used as a ZSH Line Editor widget activated by the CTRL+F keyboard shortcut. 1. Press CTRL+F 2. Describe your command or goal -3. Press enter +3. Press Enter -The generated command will be inserted into your shell prompt after a few seconds! +The generated command will be inserted into your shell prompt after a brief processing period. #### Ollama -Before running ShellOracle with Ollama, you must first pull the model you want to use. By default, ShellOracle uses the -`codellama:13b model`. To pull the default model run: +Before using ShellOracle with Ollama, pull the model you want to use. The default model is `codellama:13b`. To pull the +default model, run: ```zsh ollama pull codellama:13b @@ -60,56 +84,77 @@ ollama pull codellama:13b #### OpenAI -To run ShellOracle with the OpenAI provider, you must first create an -[API key](https://platform.openai.com/account/api-keys). Edit your ~/.shelloracle/config.toml to change your provider -and enter your API key. +To use ShellOracle with the OpenAI provider, create an [API key](https://platform.openai.com/account/api-keys). Edit +your `~/.shelloracle/config.toml` to change your provider and enter your API key. #### Tips -1. If you hit CTRL+F with text already in your ZLE buffer, all the text left of your cursor will be carried over to your ShellOracle prompt -2. UP_ARROW and DOWN_ARROW will cycle through your prompt history -3. ShellOracle can be chained together with other commands; try: `echo "find all the python files in my cwd" | shor` +1. If you press CTRL+F with text in your ZLE buffer, all text left of your cursor will carry over to your ShellOracle + prompt. +2. UP_ARROW and DOWN_ARROW cycle through your prompt history. +3. ShellOracle can be chained with other commands; try: `echo "find all the python files in my cwd" | shor` #### Other ways to run ShellOracle -ShellOracle can also be run as a python module, with `python3 -m shelloracle`, or with its entrypoint `shor`. +ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`. > [!NOTE] -> You must add your `~/.local/bin` directory to your [PATH]() for the entrypoint to work. Additionally, running -> ShellOracle with this method will not automatically insert the result into your shell prompt, so you'll have to -> copy and paste. +> Ensure your `~/.local/bin` directory is added to your [PATH]() for the entrypoint to work. Running ShellOracle this +> way won't automatically insert the result into your shell prompt. ## System Requirements -If you are using a cloud provider like OpenAI, there are no system requirements. +For cloud providers like OpenAI, there are no specific system requirements. -If you are self-hosting, system requirements vary depending on the model you are running. The Ollama model registry -has more information about +If self-hosting, system requirements vary based on the model used. Refer to the Ollama model registry for more +information. ## Configuration -ShellOracle configuration is handled by the ~/.shelloracle/config.toml file. The configuration looks like this: +ShellOracle's configuration is your gateway to tailoring the utility to match your preferences and requirements. +The `~/.shelloracle/config.toml` file serves as the control center for customizing various aspects of ShellOracle's +behavior. + +### ShellOracle Settings + +The `[shelloracle]` section in the configuration file lets you define global settings for ShellOracle: ```toml [shelloracle] -# Shell oracle configuration settings provider = "Ollama" +``` +Set the `provider` key to specify the Language Model (LLM) backend, with options currently including "Ollama" and " +OpenAI." + +### Provider Settings + +Provider-specific configurations are handled through tags such as `[provider.Ollama]` or `[provider.OpenAI]`. Here's an +example for the Ollama provider: + +```toml [provider.Ollama] -# Provider settings +host = "localhost" +port = 11434 model = "codellama:13b" +system_prompt = "..." +``` +Change these options to match your desired configuration. + +For OpenAI, if you opt for this provider, you'll need to provide your API key and specify the desired model: + +```toml [provider.OpenAI] -api_key = "" +api_key = "your-api-key-here" model = "gpt-3.5-turbo" +system_prompt = "..." ``` -Setting the `provider` key lets ShellOracle know what LLM backend to use. Currently, the options for this field are -"Ollama" and "OpenAI". - -Provider specific configuration is handled through the `[Provider.NAME]` tags. +*The provided configuration options are not exhaustive, and your default configuration may vary slightly. +Nevertheless, the fundamental concept remains the same.* -## Contributing +## Feedback -If you run into any problems, feel free to [file an issue](https://github.com/djcopley/ShellOracle/issues/new). -Feature requests are always welcome. If you wish to contribute, open a pull-request. +Encountered problems? [File an issue](https://github.com/djcopley/ShellOracle/issues/new). Feature requests are welcome, +and contributions can be made by opening a pull request. \ No newline at end of file From 6d4e88d80190ccc4a927f30994d6aed2d3ed2940 Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Tue, 2 Jan 2024 13:15:27 -0500 Subject: [PATCH 3/6] Re-arrange readme --- README.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 73bcf5e..2546ab3 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,13 @@ ollama pull codellama:13b To use ShellOracle with the OpenAI provider, create an [API key](https://platform.openai.com/account/api-keys). Edit your `~/.shelloracle/config.toml` to change your provider and enter your API key. +#### Other ways to run ShellOracle + +ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`; however, +there are a few caveats with this method: +- Ensure your `~/.local/bin` directory is added to your PATH variable for the entrypoint to work. +- Running ShellOracle with this method will not automatically insert the result into your shell prompt. + #### Tips 1. If you press CTRL+F with text in your ZLE buffer, all text left of your cursor will carry over to your ShellOracle @@ -94,14 +101,6 @@ your `~/.shelloracle/config.toml` to change your provider and enter your API key 2. UP_ARROW and DOWN_ARROW cycle through your prompt history. 3. ShellOracle can be chained with other commands; try: `echo "find all the python files in my cwd" | shor` -#### Other ways to run ShellOracle - -ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`. - -> [!NOTE] -> Ensure your `~/.local/bin` directory is added to your [PATH]() for the entrypoint to work. Running ShellOracle this -> way won't automatically insert the result into your shell prompt. - ## System Requirements For cloud providers like OpenAI, there are no specific system requirements. From 8ec5eaa549212932dde03ca0c5f0dbb71e9f21a9 Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Tue, 2 Jan 2024 13:18:15 -0500 Subject: [PATCH 4/6] Revision 2 --- README.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2546ab3..1e9fd6d 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Explore our dynamic features and look forward to more exciting updates by giving - [Installation](#installation) - [Usage](#usage) - [Configuration](#configuration) +- [System Requirements](#system-requirements) - [Feedback](#feedback) ## Introduction @@ -73,7 +74,7 @@ ShellOracle is designed to be used as a ZSH Line Editor widget activated by the The generated command will be inserted into your shell prompt after a brief processing period. -#### Ollama +**Ollama** Before using ShellOracle with Ollama, pull the model you want to use. The default model is `codellama:13b`. To pull the default model, run: @@ -82,32 +83,25 @@ default model, run: ollama pull codellama:13b ``` -#### OpenAI +**OpenAI** To use ShellOracle with the OpenAI provider, create an [API key](https://platform.openai.com/account/api-keys). Edit your `~/.shelloracle/config.toml` to change your provider and enter your API key. -#### Other ways to run ShellOracle +**Other ways to run ShellOracle** ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`; however, there are a few caveats with this method: - Ensure your `~/.local/bin` directory is added to your PATH variable for the entrypoint to work. - Running ShellOracle with this method will not automatically insert the result into your shell prompt. -#### Tips +**Tips** 1. If you press CTRL+F with text in your ZLE buffer, all text left of your cursor will carry over to your ShellOracle prompt. 2. UP_ARROW and DOWN_ARROW cycle through your prompt history. 3. ShellOracle can be chained with other commands; try: `echo "find all the python files in my cwd" | shor` -## System Requirements - -For cloud providers like OpenAI, there are no specific system requirements. - -If self-hosting, system requirements vary based on the model used. Refer to the Ollama model registry for more -information. - ## Configuration ShellOracle's configuration is your gateway to tailoring the utility to match your preferences and requirements. @@ -123,8 +117,8 @@ The `[shelloracle]` section in the configuration file lets you define global set provider = "Ollama" ``` -Set the `provider` key to specify the Language Model (LLM) backend, with options currently including "Ollama" and " -OpenAI." +Set the `provider` key to specify the Language Model (LLM) backend, with options currently including "Ollama" and +"OpenAI." ### Provider Settings @@ -153,6 +147,14 @@ system_prompt = "..." *The provided configuration options are not exhaustive, and your default configuration may vary slightly. Nevertheless, the fundamental concept remains the same.* + +## System Requirements + +For cloud providers like OpenAI, there are no specific system requirements. + +If self-hosting, system requirements vary based on the model used. Refer to the Ollama model registry for more +information. + ## Feedback Encountered problems? [File an issue](https://github.com/djcopley/ShellOracle/issues/new). Feature requests are welcome, From 383d0f0173ea973c2fedeab5f941ea82fb3497e7 Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Tue, 2 Jan 2024 13:20:45 -0500 Subject: [PATCH 5/6] Revision 4 --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1e9fd6d..2bd732a 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ ShellOracle is designed to be used as a ZSH Line Editor widget activated by the The generated command will be inserted into your shell prompt after a brief processing period. -**Ollama** +### Ollama Before using ShellOracle with Ollama, pull the model you want to use. The default model is `codellama:13b`. To pull the default model, run: @@ -83,19 +83,19 @@ default model, run: ollama pull codellama:13b ``` -**OpenAI** +### OpenAI To use ShellOracle with the OpenAI provider, create an [API key](https://platform.openai.com/account/api-keys). Edit your `~/.shelloracle/config.toml` to change your provider and enter your API key. -**Other ways to run ShellOracle** +### Other ways to run ShellOracle ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`; however, there are a few caveats with this method: - Ensure your `~/.local/bin` directory is added to your PATH variable for the entrypoint to work. - Running ShellOracle with this method will not automatically insert the result into your shell prompt. -**Tips** +### Tips 1. If you press CTRL+F with text in your ZLE buffer, all text left of your cursor will carry over to your ShellOracle prompt. From 000b56b67857b492c7b1d33942a4067991441ef8 Mon Sep 17 00:00:00 2001 From: Daniel Copley Date: Tue, 2 Jan 2024 13:21:46 -0500 Subject: [PATCH 6/6] reword --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2bd732a..05ee46f 100644 --- a/README.md +++ b/README.md @@ -61,8 +61,8 @@ curl -sSL https://raw.githubusercontent.com/djcopley/ShellOracle/master/installe ``` > [!NOTE] -> ShellOracle uses Ollama as its default Language Model (LLM) provider. Follow the installation -> instructions [here](https://ollama.ai/). +> ShellOracle uses Ollama as its default Language Model (LLM) provider. If you are going to use it, follow the +> installation instructions [here](https://ollama.ai/). ## Usage