Skip to main content

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 logo

ShellOracle

Tests PyPI version PyPI Supported Python Versions Downloads

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, LocalAI, and OpenAI!

ShellOracle

Show your support for ShellOracle and keep an eye out for exciting new developments by clicking the ⭐ and a 👀!

Table of Contents

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 install the shelloracle package
    pipx install shelloracle
    
  2. Configure ShellOracle and follow the prompts
    shor configure
    
  3. Refer to the 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
    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 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:

ollama pull dolphin-mistral

Refer to the Ollama docs for installation, available models, and usage.

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.

LocalAI

Refer to the LocalAI docs for installation, available models, and usage.

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.

System Requirements

Software

ShellOracle supports BASH and ZSH 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. Feature requests are welcome, and contributions can be made by opening a pull request.

License

This software is licensed under the GPLv3 license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shelloracle-1.5.0.tar.gz (40.5 kB view details)

Uploaded Source

Built Distribution

shelloracle-1.5.0-py3-none-any.whl (39.9 kB view details)

Uploaded Python 3

File details

Details for the file shelloracle-1.5.0.tar.gz.

File metadata

  • Download URL: shelloracle-1.5.0.tar.gz
  • Upload date:
  • Size: 40.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for shelloracle-1.5.0.tar.gz
Algorithm Hash digest
SHA256 4e14cb3fcc6e9bf5d7a7f837e64c6d3147dcda2e8986a2c666d825e29eaec4ed
MD5 9b539579876a8e53a95a25d952d4d228
BLAKE2b-256 1af8761ca1f708f04627cc0f1895b4cfc21f2d7e32751890cb9215d6e1ea256b

See more details on using hashes here.

File details

Details for the file shelloracle-1.5.0-py3-none-any.whl.

File metadata

  • Download URL: shelloracle-1.5.0-py3-none-any.whl
  • Upload date:
  • Size: 39.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for shelloracle-1.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9ddf02a48ddde9e38f432cf864117da0c6cdbe6d7cc5300ebc1641e75f48690c
MD5 826cf05b2429d809a03d554b8ee483bc
BLAKE2b-256 94f4de9010124b0f24b288a16819ec669afb691a28dfd7a0b6e22aaf6fc2d29d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page