Type something to search...



8.3k 652
04 May, 2024

What is ShellGPT

ShellGPT is a command-line productivity tool powered by AI large language models (LLM). This command-line tool offers streamlined generation of shell commands, code snippets, documentation, eliminating the need for external resources (like Google search). Supports Linux, macOS, Windows and compatible with all major Shells like PowerShell, CMD, Bash, Zsh, etc.


Terminal window
pip install shell-gpt

You’ll need an OpenAI API key, you can generate one here. You will be prompted for your key which will then be stored in ~/.config/shell_gpt/.sgptrc.


ShellGPT is designed to quickly analyse and retrieve information. It’s useful for straightforward requests ranging from technical configurations to general knowledge.

Terminal window
sgpt "What is the fibonacci sequence"
# -> The Fibonacci sequence is a series of numbers where each number ...

ShellGPT accepts prompt from both stdin and command line argument. Whether you prefer piping input through the terminal or specifying it directly as arguments, sgpt got you covered. For example, you can easily generate a git commit message based on a diff:

Terminal window
git diff | sgpt "Generate git commit message, for my changes"
# -> Added main feature details into README.md

You can analyze logs from various sources by passing them using stdin, along with a prompt. This enables you to quickly identify errors and get suggestions for possible solutions:

Terminal window
docker logs -n 20 my_app | sgpt "check logs, find errors, provide possible solutions"
Error Detected: Connection timeout at line 7.
Possible Solution: Check network connectivity and firewall settings.
Error Detected: Memory allocation failed at line 12.
Possible Solution: Consider increasing memory allocation or optimizing application memory usage.

Shell commands

Have you ever found yourself forgetting common shell commands, such as find, and needing to look up the syntax online? With --shell or shortcut -s option, you can quickly generate and execute the commands you need right in the terminal.

Terminal window
sgpt --shell "find all json files in current folder"
# -> find . -type f -name "*.json"
# -> [E]xecute, [D]escribe, [A]bort: e

Shell GPT is aware of OS and $SHELL you are using, it will provide shell command for specific system you have. For instance, if you ask sgpt to update your system, it will return a command based on your OS. Here’s an example using macOS:

Terminal window
sgpt -s "update my system"
# -> sudo softwareupdate -i -a
# -> [E]xecute, [D]escribe, [A]bort: e

The same prompt, when used on Ubuntu, will generate a different suggestion:

Terminal window
sgpt -s "update my system"
# -> sudo apt update && sudo apt upgrade -y
# -> [E]xecute, [D]escribe, [A]bort: e

Let’s try it with Docker:

Terminal window
sgpt -s "start nginx container, mount ./index.html"
# -> docker run -d -p 80:80 -v $(pwd)/index.html:/usr/share/nginx/html/index.html nginx
# -> [E]xecute, [D]escribe, [A]bort: e

We can still use pipes to pass input to sgpt and get generate shell commands:

Terminal window
cat data.json | sgpt -s "POST localhost with json"
# -> curl -X POST -H "Content-Type: application/json" -d '{"a": 1, "b": 2}' http://localhost
# -> [E]xecute, [D]escribe, [A]bort: e

Applying additional shell magic in our prompt, in this example passing file names to ffmpeg:

Terminal window
# -> 1.mp4 2.mp4 3.mp4
sgpt -s "ffmpeg combine $(ls -m) into one video file without audio."
# -> ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 -filter_complex "[0:v] [1:v] [2:v] concat=n=3:v=1 [v]" -map "[v]" out.mp4
# -> [E]xecute, [D]escribe, [A]bort: e

Shell integration

Shell integration enables the use of ShellGPT with hotkeys in your terminal, supported by both Bash and ZSH shells. This feature puts sgpt completions directly into terminal buffer (input line), allowing for immediate editing of suggested commands.


To install shell integration, run sgpt --install-integration and restart your terminal to apply changes. This will add few lines to your .bashrc or .zshrc file. After that, you can use Ctrl+l (by default) to invoke ShellGPT. When you press Ctrl+l it will replace you current input line (buffer) with suggested command. You can then edit it and just press Enter to execute.

Generating code

By using the --code or -c parameter, you can specifically request pure code output, for instance:

Terminal window
sgpt --code "solve fizz buzz problem using python"
for i in range(1, 101):
if i % 3 == 0 and i % 5 == 0:
elif i % 3 == 0:
elif i % 5 == 0:

Since it is valid python code, we can redirect the output to a file:

Terminal window
sgpt --code "solve classic fizz buzz problem using Python" > fizz_buzz.py
python fizz_buzz.py
# 1
# 2
# Fizz
# 4
# Buzz
# ...

We can also use pipes to pass input:

Terminal window
cat fizz_buzz.py | sgpt --code "Generate comments for each line of my code"
# Loop through numbers 1 to 100
for i in range(1, 101):
# Check if number is divisible by both 3 and 5
if i % 3 == 0 and i % 5 == 0:
# Print "FizzBuzz" if number is divisible by both 3 and 5
# Check if number is divisible by 3
elif i % 3 == 0:
# Print "Fizz" if number is divisible by 3
# Check if number is divisible by 5
elif i % 5 == 0:
# Print "Buzz" if number is divisible by 5
# If number is not divisible by 3 or 5, print the number itself

Chat Mode

Often it is important to preserve and recall a conversation. sgpt creates conversational dialogue with each LLM completion requested. The dialogue can develop one-by-one (chat mode) or interactively, in a REPL loop (REPL mode). Both ways rely on the same underlying object, called a chat session. The session is located at the configurable CHAT_CACHE_PATH.

To start a conversation, use the --chat option followed by a unique session name and a prompt.

Terminal window
sgpt --chat conversation_1 "please remember my favorite number: 4"
# -> I will remember that your favorite number is 4.
sgpt --chat conversation_1 "what would be my favorite number + 4?"
# -> Your favorite number is 4, so if we add 4 to it, the result would be 8.

You can use chat sessions to iteratively improve GPT suggestions by providing additional details. It is possible to use --code or --shell options to initiate --chat:

Terminal window
sgpt --chat conversation_2 --code "make a request to localhost using python"
import requests
response = requests.get('http://localhost')

Let’s ask LLM to add caching to our request:

Terminal window
sgpt --chat conversation_2 --code "add caching"
import requests
from cachecontrol import CacheControl
sess = requests.session()
cached_sess = CacheControl(sess)
response = cached_sess.get('http://localhost')

Same applies for shell commands:

Terminal window
sgpt --chat conversation_3 --shell "what is in current folder"
# -> ls
sgpt --chat conversation_3 "Sort by name"
# -> ls | sort
sgpt --chat conversation_3 "Concatenate them using FFMPEG"
# -> ffmpeg -i "concat:$(ls | sort | tr '\n' '|')" -codec copy output.mp4
sgpt --chat conversation_3 "Convert the resulting file into an MP3"
# -> ffmpeg -i output.mp4 -vn -acodec libmp3lame -ac 2 -ab 160k -ar 48000 final_output.mp3

To list all the sessions from either conversational mode, use the --list-chats or -lc option:

Terminal window
sgpt --list-chats
# .../shell_gpt/chat_cache/conversation_1
# .../shell_gpt/chat_cache/conversation_2

To show all the messages related to a specific conversation, use the --show-chat option followed by the session name:

Terminal window
sgpt --show-chat conversation_1
# user: please remember my favorite number: 4
# assistant: I will remember that your favorite number is 4.
# user: what would be my favorite number + 4?
# assistant: Your favorite number is 4, so if we add 4 to it, the result would be 8.


There is very handy REPL (read–eval–print loop) mode, which allows you to interactively chat with GPT models. To start a chat session in REPL mode, use the --repl option followed by a unique session name. You can also use “temp” as a session name to start a temporary REPL session. Note that --chat and --repl are using same underlying object, so you can use --chat to start a chat session and then pick it up with --repl to continue the conversation in REPL mode.


sgpt --repl temp
Entering REPL mode, press Ctrl+C to exit.
>>> What is REPL?
REPL stands for Read-Eval-Print Loop. It is a programming environment ...
>>> How can I use Python with REPL?
To use Python with REPL, you can simply open a terminal or command prompt ...

REPL mode can work with --shell and --code options, which makes it very handy for interactive shell commands and code generation:

sgpt --repl temp --shell
Entering shell REPL mode, type [e] to execute commands or press Ctrl+C to exit.
>>> What is in current folder?
>>> Show file sizes
ls -lh
>>> Sort them by file sizes
ls -lhS
>>> e (enter just e to execute commands, or d to describe them)

To provide multiline prompt use triple quotes """:

sgpt --repl temp
Entering REPL mode, press Ctrl+C to exit.
>>> """
... Explain following code:
... import random
... print(random.randint(1, 10))
... """
It is a Python script that uses the random module to generate and print a random integer.

Function calling

Function calls is a powerful feature OpenAI provides. It allows LLM to execute functions in your system, which can be used to accomplish a variety of tasks. To install default functions run:

Terminal window
sgpt --install-functions

ShellGPT has a convenient way to define functions and use them. In order to create your custom function, navigate to ~/.config/shell_gpt/functions and create a new .py file with the function name. Inside this file, you can define your function using the following syntax:

import subprocess
from pydantic import Field
from instructor import OpenAISchema
class Function(OpenAISchema):
Executes a shell command and returns the output (result).
shell_command: str = Field(..., example="ls -la", descriptions="Shell command to execute.")
class Config:
title = "execute_shell_command"
def execute(cls, shell_command: str) -> str:
result = subprocess.run(shell_command.split(), capture_output=True, text=True)
return f"Exit code: {result.returncode}, Output:\n{result.stdout}"

The docstring comment inside the class will be passed to OpenAI API as a description for the function, along with the title attribute and parameters descriptions. The execute function will be called if LLM decides to use your function. In this case we are allowing LLM to execute any Shell commands in our system. Since we are returning the output of the command, LLM will be able to analyze it and decide if it is a good fit for the prompt. Here is an example how the function might be executed by LLM:

Terminal window
sgpt "What are the files in /tmp folder?"
# -> @FunctionCall execute_shell_command(shell_command="ls /tmp")
# -> The /tmp folder contains the following files and directories:
# -> test.txt
# -> test.json

Note that if for some reason the function (execute_shell_command) will return an error, LLM might try to accomplish the task based on the output. Let’s say we don’t have installed jq in our system, and we ask LLM to parse JSON file:

Terminal window
sgpt "parse /tmp/test.json file using jq and return only email value"
# -> @FunctionCall execute_shell_command(shell_command="jq -r '.email' /tmp/test.json")
# -> It appears that jq is not installed on the system. Let me try to install it using brew.
# -> @FunctionCall execute_shell_command(shell_command="brew install jq")
# -> jq has been successfully installed. Let me try to parse the file again.
# -> @FunctionCall execute_shell_command(shell_command="jq -r '.email' /tmp/test.json")
# -> The email value in /tmp/test.json is johndoe@example.

It is also possible to chain multiple function calls in the prompt:

Terminal window
sgpt "Play music and open hacker news"
# -> @FunctionCall play_music()
# -> @FunctionCall open_url(url="https://news.ycombinator.com")
# -> Music is now playing, and Hacker News has been opened in your browser. Enjoy!

This is just a simple example of how you can use function calls. It is truly a powerful feature that can be used to accomplish a variety of complex tasks. We have dedicated category in GitHub Discussions for sharing and discussing functions. LLM might execute destructive commands, so please use it at your own risk❗️


ShellGPT allows you to create custom roles, which can be utilized to generate code, shell commands, or to fulfill your specific needs. To create a new role, use the --create-role option followed by the role name. You will be prompted to provide a description for the role, along with other details. This will create a JSON file in ~/.config/shell_gpt/roles with the role name. Inside this directory, you can also edit default sgpt roles, such as shell, code, and default. Use the --list-roles option to list all available roles, and the --show-role option to display the details of a specific role. Here’s an example of a custom role:

Terminal window
sgpt --create-role json_generator
# Enter role description: Provide only valid json as response.
sgpt --role json_generator "random: user, password, email, address"
"user": "JohnDoe",
"password": "p@ssw0rd",
"email": "[email protected]",
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"

Request cache

Control cache using --cache (default) and --no-cache options. This caching applies for all sgpt requests to OpenAI API:

Terminal window
sgpt "what are the colors of a rainbow"
# -> The colors of a rainbow are red, orange, yellow, green, blue, indigo, and violet.

Next time, same exact query will get results from local cache instantly. Note that sgpt "what are the colors of a rainbow" --temperature 0.5 will make a new request, since we didn’t provide --temperature (same applies to --top-probability) on previous request.

This is just some examples of what we can do using OpenAI GPT models, I’m sure you will find it useful for your specific use cases.

Runtime configuration file

You can setup some parameters in runtime configuration file ~/.config/shell_gpt/.sgptrc:

# API key, also it is possible to define OPENAI_API_KEY env.
# OpenAI host, useful if you would like to use proxy.
# Max amount of cached message per chat session.
# Chat cache folder.
# Request cache length (amount).
# Request cache folder.
# Request timeout in seconds.
# Default OpenAI model to use.
# Default color for shell and code completions.
# When in --shell mode, default to "Y" for no input.
# Disable streaming of responses
# The pygment theme to view markdown (default/describe role).
# Path to a directory with functions.
# Print output of functions when LLM uses them.
# Allows LLM to use functions.

Possible options for DEFAULT_COLOR: black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white. Possible options for CODE_THEME: https://pygments.org/styles/

Full list of arguments

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────╮
│ prompt [PROMPT] The prompt to generate completions for. │
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Large language model to use. [default: gpt-4-1106-preview] │
│ --temperature FLOAT RANGE [0.0<=x<=2.0] Randomness of generated output. [default: 0.0] │
│ --top-p FLOAT RANGE [0.0<=x<=1.0] Limits highest probable tokens (words). [default: 1.0] │
│ --editor Open $EDITOR to provide a prompt. [default: no-editor] │
│ --cache Cache completion results. [default: cache] │
│ --version Show version. │
│ --help Show this message and exit. │
╭─ Assistance Options ─────────────────────────────────────────────────────────────────────────────────────╮
│ --shell -s Generate and execute shell commands. │
│ --describe-shell -d Describe a shell command. │
│ --code -c Generate only code. │
│ --functions --no-functions Allow function calls. [default: functions] │
╭─ Chat Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --chat TEXT Follow conversation with id, use "temp" for quick session. [default: None] │
│ --repl TEXT Start a REPL (Read–eval–print loop) session. [default: None] │
│ --show-chat TEXT Show all messages from provided chat id. [default: None] │
│ --list-chats -lc List all existing chat ids. │
╭─ Role Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --role TEXT System role for GPT model. [default: None] │
│ --create-role TEXT Create role. [default: None] │
│ --show-role TEXT Show role. [default: None] │
│ --list-roles -lr List roles. │


By default, ShellGPT leverages OpenAI’s large language models. However, it also provides the flexibility to use locally hosted models, which can be a cost-effective alternative. To use local models, you will need to run your own API server. You can accomplish this by using LocalAI, a self-hosted, OpenAI-compatible API. Setting up LocalAI allows you to run language models on your own hardware, potentially without the need for an internet connection, depending on your usage. To set up your LocalAI, please follow this comprehensive guide. Remember that the performance of your local models may depend on the specifications of your hardware and the specific language model you choose to deploy.


Run the container using the OPENAI_API_KEY environment variable, and a docker volume to store cache:

Terminal window
docker run --rm \
--env OPENAI_API_KEY="your OPENAI API key" \
--volume gpt-cache:/tmp/shell_gpt \
ghcr.io/ther1d/shell_gpt --chat rainbow "what are the colors of a rainbow"

Example of a conversation, using an alias and the OPENAI_API_KEY environment variable:

Terminal window
alias sgpt="docker run --rm --env OPENAI_API_KEY --volume gpt-cache:/tmp/shell_gpt ghcr.io/ther1d/shell_gpt"
export OPENAI_API_KEY="your OPENAI API key"
sgpt --chat rainbow "what are the colors of a rainbow"
sgpt --chat rainbow "inverse the list of your last answer"
sgpt --chat rainbow "translate your last answer in french"

You also can use the provided Dockerfile to build your own image:

Terminal window
docker build -t sgpt .