ShellGenius

ShellGenius is a CLI tool that turns natural-language task descriptions into shell commands.

Powered by OpenAI models, ShellGenius prints a suggested command in a fenced code block, followed by a short explanation. By default it shows the response and exits. With --execute, it can run the parsed command for you.

This repository is dedicated to ShellGenius as a standalone tool within the LLM-Toolbox, a curated suite of AI-powered CLI tools built to modernize your terminal experience. Here, you will find all resources, discussions, and updates specifically related to ShellGenius.

To explore other tools within the LLM-Toolbox—such as commitgen, the automatic commit message generator—please visit the LLM-Toolbox repository.

Table of Contents

1. Video Demos
   1. Video Frames Extraction
   2. Batch Git Repository Update
   3. Directory Synchronization
   4. Find and Copy Files with Keywords
2. Installation
   1. Install via pipx (recommended)
   2. OpenAI API key
3. Usage
   1. Regarding the Quotes
   2. Creating an Alias
   3. Make ShellGenius Respond in Your Native Language
4. Examples
   1. Remove Duplicate Lines
   2. Extract Columns in a File
   3. Download a File
   4. Number of Lines in a File
5. Limitations
6. License

Video Demos

Video Frames Extraction

shellgenius_extract_frames_demo.mp4

Batch Git Repository Update

Directory Synchronization

shellgenius_sync_dir_demo.mp4

Find and Copy Files with Keywords

Installation

Ensure you have Python 3.10 or later installed on your system. To install ShellGenius, use the following command:

python3 -m pip install shellgenius

Install via pipx (recommended)

pipx is an alternative package manager for Python applications. It allows you to install and run Python applications in isolated environments, preventing conflicts between dependencies and ensuring that each application uses its own set of packages. I recommend using pipx to install ShellGenius.

First, install pipx if you haven't already:

• On macOS and Linux:

  python3 -m pip install --user pipx
  python3 -m pipx ensurepath
  

Alternatively, you can use your package manager (brew, apt, etc.).

• On Windows:

  py -m pip install --user pipx
  py -m pipx ensurepath
  

Once pipx is installed, you can install ShellGenius using the following command:

pipx install shellgenius

OpenAI API key

ShellGenius requires an OpenAI API key to function. You can obtain a key by signing up for an account at OpenAI's website.

Once you have your API key, set it as an environment variable:

• On macOS and Linux:

  export OPENAI_API_KEY="your-api-key-here"

  To avoid having to type it everyday, you can create a file with the key:

  echo "your-api-key" > ~/.openai-api-key.txt

  Note: Remember to replace "your-api-key" with your actual API key.

  And then, you can add this to your shell configuration file (.bashrc, .zshrc, etc.):

  export OPENAI_API_KEY="$(cat ~/.openai-api-key.txt)"

• On Windows:

  setx OPENAI_API_KEY your_key
  

Usage

Run shellgenius followed by a description of the task:

shellgenius "description of your task"

The default flow asks the model for a command, prints the response, and exits.

To run the generated command, add --execute:

shellgenius --execute "description of your task"

When --execute is used, ShellGenius honors the fenced shell language. On Unix, bash, sh, and zsh fences run through that shell, while a shell fence or no language falls back to sh. On Windows, powershell fences, shell, and no language run through PowerShell. ShellGenius rejects fences it cannot execute on the current platform instead of silently switching shells.

Useful options:

• -m, --model selects the model. The default is gpt-5.4-mini.
• --no-stream disables the live Rich view.
• -p, --plain prints plain text instead of Rich output.
• -c, --command-only prints only the parsed command and cannot be combined with --execute.
• -x, --execute runs the generated command.
• -y, --yes skips the confirmation prompt when used with --execute.

When stdout is not a TTY, ShellGenius switches to plain buffered output automatically. In non-interactive mode, --execute also requires --yes.

For local development, mocked tests run by default. Opt in to real OpenAI smoke tests with uv run pytest --run-live -m real or GATE_REAL=1 gate, which forwards --run-live -m real to pytest across isolated per-version test environments.

Regarding the Quotes

The quotes are not necessary when the task description does not contain a single quote, or a special character.

Not necessary:

shellgenius compile and run myprogramm.cpp

Necessary:

shellgenius "find and replace 'oldtext' with 'newtext' in *.txt files"

Creating an Alias

To further enhance the usability of ShellGenius, even with the presence of autocompletion, I recommend to create an alias for effortless access. One suggested alias is ??.

By defining an alias, you can invoke ShellGenius simply by typing ?? followed by your task description, eliminating the need to type the full command each time.

To create the alias, add the following line to your shell configuration file (~/.bashrc, ~/.bash_profile, or ~/.zshrc, depending on your shell):

alias '??'='shellgenius'

After adding the alias, you can use ShellGenius by typing ?? instead of shellgenius, making your command-line experience even more seamless and efficient.

An alias also works well for pipe-friendly command output:

?? -c "find the ten largest files here"

Note: Make sure to restart your shell or run source ~/.bashrc (or the corresponding file for your shell) for the alias to take effect.

Make ShellGenius Respond in Your Native Language

You can describe your task in your native language, but ShellGenius might still respond in English. If that happens, you can add a specific request at the end of your task description. Here's an example:

shellgenius "Description of your task in your own language. Réponds en français."

In the above command, "Réponds en français" is a request for ShellGenius to respond in French. You can replace this with a similar phrase in your language. For example, if you want the response in German, you can use "Antworte auf Deutsch". ShellGenius will then oblige and respond in the requested language.

shellgenius "Erstellt eine Datei. Antworte auf Deutsch."

Examples

Here are some examples of ShellGenius in action:

Remove Duplicate Lines

shellgenius "remove duplicate lines from file.txt"

Output:

```bash
awk '!seen[$0]++' file.txt
```

Explanation:
* awk is a pattern scanning and processing language
* '!seen[$0]++' is an awk expression that removes duplicate lines
* file.txt is the name of the file to process

---

Extract Columns in a File

shellgenius "extract columns 1, 3, and 5 from data.csv"

Output:

```bash
cut -d',' -f1,3,5 data.csv
```

Explanation:
* cut command is used to extract portions of lines from files
* -d',' specifies the delimiter as a comma
* -f1,3,5 specifies the columns to extract
* data.csv is the input CSV file

---

Download a File

shellgenius "download a file from https://example.com/file.zip"

Output:

```bash
curl -OJL https://example.com/file.zip
```

Explanation:
* curl is a command-line tool for transferring data using various protocols
* -O option saves the downloaded file with its original name
* -J option tries to set the file name based on the URL
* -L option follows redirects if the URL points to a different location
* https://example.com/file.zip is the URL of the file to download

---

Number of Lines in a File

shellgenius "count the number of lines in a file called data.csv"

Output:

```bash
wc -l data.csv
```

Explanation:
* wc is a word, line, and byte count utility
* -l flag counts the number of lines
* data.csv is the target file

Limitations

ShellGenius is powered by an AI model and may not always generate the most efficient or accurate commands. Exercise caution when executing commands, especially when working with sensitive data or critical systems.

License

ShellGenius is released under the Apache 2.0 Licence.

---

https://github.com/sderev/shellgenius