https://github.com/djcopley/shelloracle
A terminal utility for intelligent shell command generation
https://github.com/djcopley/shelloracle
ai bash developer-tools fish gemini linux llm localai macos ollama openai openai-api terminal xai zsh
Last synced: 12 days ago
JSON representation
A terminal utility for intelligent shell command generation
- Host: GitHub
- URL: https://github.com/djcopley/shelloracle
- Owner: djcopley
- License: gpl-3.0
- Created: 2023-12-11T20:23:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-23T20:06:32.000Z (28 days ago)
- Last Synced: 2025-04-01T14:01:51.831Z (19 days ago)
- Topics: ai, bash, developer-tools, fish, gemini, linux, llm, localai, macos, ollama, openai, openai-api, terminal, xai, zsh
- Language: Python
- Homepage:
- Size: 1.71 MB
- Stars: 256
- Watchers: 2
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
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 `dolphin-mistral`, run:
```shell
ollama pull dolphin-mistral
```
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.
### 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.