# ShellGPT (sgpt): a CLI that turns prompts into shell commands

> ShellGPT is a Python CLI that sends prompts and piped stdin to an LLM and prints answers, code or shell commands. It installs with pip, defaults to OpenAI, and can be pointed at Ollama with the caveat that it is not optimized for local models.

**TheR1D/shell_gpt** — A command-line productivity tool powered by AI large language models like GPT-5, will help you accomplish your tasks faster and more efficiently.

- Repository: https://github.com/TheR1D/shell_gpt
- Stars: 12,286 · Forks: 975
- Language: Python
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/ther1d-shell-gpt

## The gap ShellGPT fills between your terminal and an LLM

You forget the syntax of find, or you have twenty lines of docker logs and no patience to read them. The usual move is a browser tab, a search engine and a copy-paste round trip. ShellGPT replaces that with a single command that accepts a prompt as an argument or as piped stdin and prints the answer in the terminal. The README frames it as generation of shell commands, code snippets and documentation without external resources. The intended user is a developer or sysadmin who already works in Bash, Zsh, PowerShell or CMD and wants the model inside that context rather than beside it. It is not an agent that edits your repository, and it does not run a background service. Each invocation is one request, one response, and for shell commands, one confirmation prompt.

## How sgpt handles prompts, pipes and the -s command loop

The mechanism is deliberately thin. The sgpt entry point is declared in pyproject.toml as sgpt = "sgpt:cli", built on typer and click, with rich for rendering. Input arrives either as a command-line argument or through stdin, and the README shows redirection with <, heredocs with << EOF, and here-strings with <<<. That same stdin channel is what makes the pipe examples work: git diff piped into a prompt that asks for a commit message, or docker logs -n 20 my_app piped into a request to find errors.

The --shell flag (short form -s) changes the output contract. Instead of prose, sgpt returns a single command and then asks for a decision, shown in the README as [E]xecute, [D]escribe, [A]bort. Choosing e runs it. The README states that the tool is aware of your OS and $SHELL, so the same prompt produces sudo softwareupdate -i -a on macOS and sudo apt update && sudo apt upgrade -y on Ubuntu. If you want the command without the prompt, --no-interaction prints it to stdout so it can be piped somewhere else, for example into pbcopy.

Shell integration is a separate path. Running sgpt --install-integration appends a few lines to .bashrc or .zshrc, and after a terminal restart Ctrl+l replaces the current input buffer with a suggested command that you can still edit before pressing Enter. That is the most invasive part of the tool, and it is opt-in.

## Installing ShellGPT and running a first command

Installation is a single pip command. The package name on PyPI is shell-gpt, while the installed binary is sgpt.

```bash
pip install shell-gpt
```

On first run you are prompted for an OpenAI API key, which is then stored in ~/.config/shell_gpt/.sgptrc. The README points to the OpenAI platform for generating the key and notes that the API is not free of charge. The declared dependency range pins openai >= 2.0.0, < 3.0.0, and Python 3.10 or newer is required.

A first useful invocation is a plain question, which prints prose to stdout.

```bash
sgpt "What is the fibonacci sequence"
```

The more interesting first use is the shell mode. Ask for something you would otherwise look up, and you get a command plus the execute/describe/abort prompt.

```bash
sgpt --shell "find all json files in current folder"
```

The README shows the result as find . -type f -name "*.json" followed by the decision prompt. Press e to run it, d to read an explanation first, or a to abort. If you would rather inspect the command elsewhere, add --no-interaction and it is printed to stdout with no prompt.

For code, --code (or -c) requests pure code output, which is why the README can redirect it straight into a file.

```bash
sgpt --code "solve classic fizz buzz problem using Python" > fizz_buzz.py
python fizz_buzz.py
```

There is also a container path. The repository ships a Dockerfile based on python:3-slim that installs the package and sets ENTRYPOINT ["sgpt"], with SHELL_INTERACTION and PRETTIFY_MARKDOWN both set to false and a VOLUME at /tmp/shell_gpt.

## What ShellGPT is not good at

The README is unusually direct about the local-model case: ShellGPT is not optimized for local models and may not work as expected. Running Ollama is possible, and the project links a wiki guide for it, but the default path assumes a hosted OpenAI model. If your reason for using a CLI assistant is to keep data on your own machine, you are working against the grain of the tool rather than with it.

The second constraint is the trust boundary around -s. The generated command is not sandboxed or validated; the only gate is the interactive prompt. The README's own examples include sudo commands and a docker run that binds port 80. In a non-interactive pipeline with --no-interaction, that gate disappears by design, so anything consuming the output is responsible for reviewing it. The prompt is a convenience, not a safety mechanism.

Third, the tool has no memory of your repository beyond what you pipe into it. There is no indexing step, no project context file mentioned in the README, and no diff-aware behaviour other than the stdin examples. For questions that require understanding a codebase, a piped diff or log is the only context you get to supply, and you pay for those tokens on every call.

## ShellGPT versus a general-purpose coding agent

The closest alternative in practice is an editor-integrated or repository-aware agent that reads files itself, plans multi-step edits and runs tests. The difference is context acquisition. ShellGPT receives context only through an argument or stdin, which the README demonstrates with git diff, docker logs and file redirection. That makes it fast and predictable: one prompt, one response, no tool loop. A coding agent inverts this, spending more tokens and time to discover context on its own in exchange for handling tasks that span many files. ShellGPT is the better fit for a single question with a known input, and the worse fit for "refactor this module". The project's own topic list (cli, commands, cheat-sheet, productivity) describes the former, not the latter.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-07-02. Releases are infrequent rather than continuous: 1.5.1 on 2026-05-06, 1.5.0 on 2026-01-28, and 1.4.5 back on 2025-04-08. That cadence matters if you depend on a specific provider SDK. The openai dependency is capped below 3.0.0, so a major SDK release will require a ShellGPT release rather than a silent upgrade on your side. The optional litellm extra is pinned exactly to 1.83.4, which means installing that extra can conflict with other packages in the same environment; keeping ShellGPT in its own virtualenv or in the provided container avoids that class of problem. The licence is MIT, declared both in the LICENSE file and in pyproject.toml, which permits commercial and closed-source use with the usual requirement to keep the copyright notice; that is a description of the terms, not legal advice. Your ongoing cost is the API bill, and it scales with how much you pipe into prompts.

## Configuration surface worth knowing before you commit

Everything persistent lives in ~/.config/shell_gpt/.sgptrc, written when you supply the API key. That single file is what you back up, template across machines, or replace when switching between a hosted provider and a local backend. The Dockerfile shows the environment-variable side of the same configuration: SHELL_INTERACTION, PRETTIFY_MARKDOWN, OS_NAME and SHELL_NAME, with OS_NAME and SHELL_NAME both set to auto. If you run sgpt inside a container or over SSH, those two variables are the ones that decide whether the generated command matches the machine you are actually on. The README does not document a rollback procedure for sgpt --install-integration beyond the fact that it appends lines to .bashrc or .zshrc, so if you try it, note what was added before you restart the terminal.

## Conclusion

Adopt ShellGPT if you live in a terminal and want prompts, pipes and the -s command generator in one binary that installs from pip and stores its config in ~/.config/shell_gpt/.sgptrc. Skip it if your environment forbids sending diffs, logs or file contents to a hosted API, or if you expect a polished local-model experience, since the README states ShellGPT is not optimized for local models. Before rolling it out, verify the config file path your user actually gets, confirm which model and provider the default configuration resolves to, and read the generated command before pressing e at the [E]xecute, [D]escribe, [A]bort prompt.

## FAQ

### What is ShellGPT?

ShellGPT is a command-line productivity tool powered by large language models. It generates shell commands, code snippets and documentation from a prompt or piped input, and runs on Linux, macOS and Windows across major shells.

### How to install ShellGPT?

Install it with pip install shell-gpt. The package requires Python 3.10 or newer, and on first run you are prompted for an OpenAI API key, which is stored in ~/.config/shell_gpt/.sgptrc.

### how to use shellgpt

Run sgpt followed by a prompt, or pipe input into it, for example git diff | sgpt "Generate git commit message, for my changes". Use --shell to get an executable command with an execute, describe or abort prompt, and --code to get pure code output.

### how to install shell gpt in linux

The README gives one installation path for all platforms: pip install shell-gpt. It states support for Linux, macOS and Windows and compatibility with shells such as Bash, Zsh, PowerShell and CMD. No distribution-specific package is documented.

### is shell gpt free

The tool itself is MIT licensed, but the default backend is the OpenAI API, which the README says is not free of charge and links to OpenAI pricing for. The README also notes that open-source models can be run locally for free via a backend such as Ollama.

### how to install shell gpt in kali linux

The README does not describe a Kali-specific package or repository. The only installation command it gives is pip install shell-gpt, which the README presents as working across Linux, macOS and Windows.

## Sources

- [Issues](https://github.com/TheR1D/shell_gpt/issues)
- [License: MIT](https://github.com/TheR1D/shell_gpt/blob/main/LICENSE)
- [README](https://github.com/TheR1D/shell_gpt/blob/main/README.md)
- [Releases](https://github.com/TheR1D/shell_gpt/releases)
- [TheR1D/shell_gpt on GitHub](https://github.com/TheR1D/shell_gpt)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ther1d-shell-gpt