ShellOracle is a pluggable terminal utility that takes a natural language description of a command and substitutes it into your terminal buffer.
Project description
ShellOracle
ShellOracle is an innovative terminal utility designed for intelligent shell command generation, bringing a new level of efficiency to your command-line interactions.
Explore our dynamic features and look forward to more exciting updates by giving us a ⭐ and a 👀
Table of Contents
Introduction
Meet ShellOracle—a handy tool that makes working with the command line a bit smoother. This terminal utility lets you create shell commands by describing what you want to do in plain language. ShellOracle simplifies the process of crafting complex commands by removing the need to google and comb man pages.
Why ShellOracle?
-
No More Memorizing: Forget about remembering complex shell commands. Just tell ShellOracle what you need, and it'll generate the command for you.
-
Save Time, Stay Focused: Say goodbye to manual command crafting. ShellOracle helps you save time and concentrate on what really matters by using natural language descriptions.
-
Adaptable to Your Needs: Whether it's a quick one-liner or a sequence of commands, ShellOracle is flexible. It supports Unix pipes and keeps track of your command history.
-
Your Control, Your Way: Run ShellOracle as a self-hosted utility to have complete control. Tailor it to your preferences and make it work just the way you want.
Give it a try and see how it fits into your workflow!
Features
Key features of ShellOracle include:
- 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
Installing ShellOracle is easy!
- First, pip install the
shelloracle
packagepython3 -m pip install shelloracle
- Next, run
shelloracle --init
and follow the promptspython3 -m shelloracle --init
Ollama
[!IMPORTANT] ShellOracle uses Ollama as its default LLM provider. If you are using the default configuration, the following steps are required.
- Install Ollama
- Download the default model
ollama pull codellama:13b
Usage
ShellOracle is designed to be used as a BASH/ZSH widget activated by the CTRL+F keyboard shortcut.
- Press CTRL+F
- Describe your command or goal
- Press Enter
The generated command will be inserted into your shell prompt after a brief processing period.
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:
ollama pull codellama:13b
OpenAI
To use ShellOracle with the OpenAI provider, create an API key. 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
- If you press CTRL+F with text in your ZLE buffer, all text left of your cursor will carry over to your ShellOracle prompt.
- UP_ARROW and DOWN_ARROW cycle through your prompt history.
- ShellOracle can be chained with other commands; try:
echo "find all the python files in my cwd" | shor
Configuration
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:
[shelloracle]
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:
[provider.Ollama]
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:
[provider.OpenAI]
api_key = "your-api-key-here"
model = "gpt-3.5-turbo"
system_prompt = "..."
System Requirements
Software
ShellOracle supports BASH and ZSH on macOS and Linux.
Hardware
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. Feature requests are welcome, and contributions can be made by opening a pull request.
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 shelloracle-0.6.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 968493ef97c0961b2601bac483b0fddcd17a5d381782775f8e98d4e00cab853a |
|
MD5 | a97c9fee7a3d1edc1eea7c1a425df47c |
|
BLAKE2b-256 | bd7e072728e170dfa93cf6ce66f1538fa95ad3eb204dd8c9eb25ca913cb3bfb7 |