ShellOracle
ShellOracle is an innovative terminal utility designed for intelligent shell command generation, bringing a new level of
efficiency to your command-line interactions. ShellOracle currently supports Ollama, OpenAI, Deepseek, LocalAI, and Grok!
Show your support for ShellOracle and keep an eye out for exciting new developments by clicking the ⭐ and a 👀!
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Providers](#providers)
- [Configuration](#configuration)
- [System Requirements](#system-requirements)
- [Feedback](#feedback)
## 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!
1. [pipx](https://pipx.pypa.io/latest/) install the `shelloracle` package
```shell
pipx install shelloracle
```
2. Configure ShellOracle and follow the prompts
```shell
shor config init
```
3. Refer to the [providers](#providers) section for specific details regarding your chosen provider.
Upgrading to the latest version of ShellOracle is just as simple!
1. pipx upgrade the `shelloracle` package
```shell
pipx upgrade shelloracle
```
*Installation with `pip` is supported, however, `pipx` is preferred for its automatic environment isolation.*
## Usage
ShellOracle is designed to be used as a BASH/ZSH/fish widget activated by the CTRL+F keyboard shortcut.
1. Press CTRL+F
2. Describe your command
3. Press Enter
The generated command will be inserted into your shell prompt after a brief processing period.
### Other ways to run ShellOracle
ShellOracle can be run as a Python module with `python3 -m shelloracle` or using its entrypoint `shor`, however,
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
prompt.
2. ⬆️ arrow and ⬇️ 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`
## Providers
### Ollama
Before using ShellOracle with Ollama, pull the model you chose in the configure step.
For example, if you chose `qwen2.5-coder`, run:
```shell
ollama pull qwen2.5-coder
```
Refer to the [Ollama docs](https://ollama.ai) for installation, available models, and usage.
### OpenAI
To use ShellOracle with OpenAI's models, 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.
You can use `shor config edit` as a shorthand to edit this file.
### Deepseek
To use ShellOracle with Deepseek's models, create an [API key](https://platform.deepseek.com/api_keys). Edit
your `~/.shelloracle/config.toml` to change your provider and enter your API key.
You can use `shor config edit` as a shorthand to edit this file.
### LocalAI
Refer to the [LocalAI docs](https://localai.io/) for installation, available models, and usage.
### LM Studio
To use ShellOracle with [LM Studio](https://lmstudio.ai/), you will first need to run a model and start the server.
For macOS users, it's recommended to utillize a model that is using the MLX runtime.
Here is an example configuration:
```toml
[shelloracle]
provider = "OpenAICompat"
[provider.OpenAICompat]
base_url = "http://localhost:1234/v1"
api_key = "lm-studio"
model = "mistralai/devstral-small-2507"
```
### XAI
To use ShellOracle with XAI's models, create an [API key](https://docs.x.ai/docs/quickstart#creating-an-api-key).
Edit your `~/.shelloracle/config.toml` to change your provider and enter your API key.
You can use `shor config edit` as a shorthand to edit this file.
### Google
To use ShellOracle with Google's models, create an [API key](https://aistudio.google.com/app/apikey).
Edit your `~/.shelloracle/config.toml` to change your provider and enter your API key.
You can use `shor config edit` as a shorthand to edit this file.
## 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. You can quickly access and edit this file using the command `shor config edit`.
## System Requirements
### Software
ShellOracle supports BASH, ZSH and fish on macOS and Linux.
### Hardware
For cloud providers like OpenAI, there are no hardware requirements.
If running locally, refer to your model for hardware requirements.
## Feedback
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.
## License
This software is licensed under the GPLv3 license.