Package: shell-gpt
ShellGPTA command-line productivity tool powered by AI large language models (LLM). This command-line tool offers streamlined generation ofshell 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.https://github.com/TheR1D/shell_gpt/assets/16740832/9197283c-db6a-4b46-bfea-3eb776dd9093Installationpipinstallshell-gptBy default, ShellGPT uses OpenAI's API and GPT-4 model. You'll need an API key, you can generate onehere. You will be prompted for your key which will then be stored in~/.config/shell_gpt/.sgptrc. OpenAI API is not free of charge, please refer to theOpenAI pricingfor more information.[!TIP]
Alternatively, you can use locally hosted open source models which are available for free. To use local models, you will need to run your own LLM backend server such asOllama. To set up ShellGPT with Ollama, please follow this comprehensiveguide.❗️Note that ShellGPT is not optimized for local models and may not work as expected.UsageShellGPTis designed to quickly analyse and retrieve information. It's useful for straightforward requests ranging from technical configurations to general knowledge.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,sgptgot you covered. For example, you can easily generate a git commit message based on a diff:gitdiff|sgpt"Generate git commit message, for my changes"# -> Added main feature details into README.mdYou can analyze logs from various sources by passing them using stdin, along with a prompt. For instance, we can use it to quickly analyze logs, identify errors and get suggestions for possible solutions:dockerlogs-n20my_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.You can also use all kind of redirection operators to pass input:sgpt"summarise"<document.txt# -> The document discusses the impact...sgpt<< EOFWhat is the best way to lear Golang?Provide simple hello world example.EOF# -> The best way to learn Golang...sgpt<<<"What is the best way to learn shell redirects?"# -> The best way to learn shell redirects is through...Shell commandsHave you ever found yourself forgetting common shell commands, such asfind, and needing to look up the syntax online? With--shellor shortcut-soption, you can quickly generate and execute the commands you need right in the terminal.sgpt--shell"find all json files in current folder"# -> find . -type f -name "*.json"# -> [E]xecute, [D]escribe, [A]bort: eShell GPT is aware of OS and$SHELLyou are using, it will provide shell command for specific system you have. For instance, if you asksgptto update your system, it will return a command based on your OS. Here's an example using macOS:sgpt-s"update my system"# -> sudo softwareupdate -i -a# -> [E]xecute, [D]escribe, [A]bort: eThe same prompt, when used on Ubuntu, will generate a different suggestion:sgpt-s"update my system"# -> sudo apt update && sudo apt upgrade -y# -> [E]xecute, [D]escribe, [A]bort: eLet's try it with Docker: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: eWe can still use pipes to pass input tosgptand generate shell commands:sgpt-s"POST localhost with"<data.json# -> curl -X POST -H "Content-Type: application/json" -d '{"a": 1, "b": 2}' http://localhost# -> [E]xecute, [D]escribe, [A]bort: eApplying additional shell magic in our prompt, in this example passing file names toffmpeg:ls# -> 1.mp4 2.mp4 3.mp4sgpt-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: eIf you would like to pass generated shell command using pipe, you can use--no-interactionoption. This will disable interactive mode and will print generated command to stdout. In this example we are usingpbcopyto copy generated command to clipboard:sgpt-s"find all json files in current folder"--no-interaction|pbcopyShell integrationThis is avery handy feature, which allows you to usesgptshell completions directly in your terminal, without the need to typesgptwith prompt and arguments. Shell integration enables the use of ShellGPT with hotkeys in your terminal, supported by both Bash and ZSH shells. This feature putssgptcompletions directly into terminal buffer (input line), allowing for immediate editing of suggested commands.https://github.com/TheR1D/shell_gpt/assets/16740832/bead0dab-0dd9-436d-88b7-6abfb2c556c1To install shell integration, runsgpt --install-integrationand restart your terminal to apply changes. This will add few lines to your.bashrcor.zshrcfile. After that, you can useCtrl+l(by default) to invoke ShellGPT. When you pressCtrl+lit will replace you current input line (buffer) with suggested command. You can then edit it and just pressEnterto execute.Generating codeBy using the--codeor-cparameter, you can specifically request pure code output, for instance:sgpt--code"solve fizz buzz problem using python"foriinrange(1,101):ifi%3==0andi%5==0:print("FizzBuzz")elifi%3==0:print("Fizz")elifi%5==0:print("Buzz")else:print(i)Since it is valid python code, we can redirect the output to a file:sgpt--code"solve classic fizz buzz problem using Python">fizz_buzz.py
pythonfizz_buzz.py# 1# 2# Fizz# 4# Buzz# ...We can also use pipes to pass input:catfizz_buzz.py|sgpt--code"Generate comments for each line of my code"# Loop through numbers 1 to 100foriinrange(1,101):# Check if number is divisible by both 3 and 5ifi%3==0andi%5==0:# Print "FizzBuzz" if number is divisible by both 3 and 5print("FizzBuzz")# Check if number is divisible by 3elifi%3==0:# Print "Fizz" if number is divisible by 3print("Fizz")# Check if number is divisible by 5elifi%5==0:# Print "Buzz" if number is divisible by 5print("Buzz")# If number is not divisible by 3 or 5, print the number itselfelse:print(i)Chat ModeOften it is important to preserve and recall a conversation.sgptcreates 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 theconfigurableCHAT_CACHE_PATH.To start a conversation, use the--chatoption followed by a unique session name and a prompt.sgpt--chatconversation_1"please remember my favorite number: 4"# -> I will remember that your favorite number is 4.sgpt--chatconversation_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--codeor--shelloptions to initiate--chat:sgpt--chatconversation_2--code"make a request to localhost using python"importrequestsresponse=requests.get('http://localhost')print(response.text)Let's ask LLM to add caching to our request:sgpt--chatconversation_2--code"add caching"importrequestsfromcachecontrolimportCacheControlsess=requests.session()cached_sess=CacheControl(sess)response=cached_sess.get('http://localhost')print(response.text)Same applies for shell commands:sgpt--chatconversation_3--shell"what is in current folder"# -> lssgpt--chatconversation_3"Sort by name"# -> ls | sortsgpt--chatconversation_3"Concatenate them using FFMPEG"# -> ffmpeg -i "concat:$(ls | sort | tr '\n' '|')" -codec copy output.mp4sgpt--chatconversation_3"Convert the resulting file into an MP3"# -> ffmpeg -i output.mp4 -vn -acodec libmp3lame -ac 2 -ab 160k -ar 48000 final_output.mp3To list all the sessions from either conversational mode, use the--list-chatsor-lcoption:sgpt--list-chats# .../shell_gpt/chat_cache/conversation_1# .../shell_gpt/chat_cache/conversation_2To show all the messages related to a specific conversation, use the--show-chatoption followed by the session name:sgpt--show-chatconversation_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.REPL ModeThere 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--reploption followed by a unique session name. You can also use "temp" as a session name to start a temporary REPL session. Note that--chatand--replare using same underlying object, so you can use--chatto start a chat session and then pick it up with--replto 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--shelland--codeoptions, 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?
ls
>>> 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.You can also enter REPL mode with initial prompt by passing it as an argument or stdin or even both:sgpt--repltemp<my_app.pyEntering REPL mode, press Ctrl+C to exit.
──────────────────────────────────── Input ────────────────────────────────────
name = input("What is your name?")
print(f"Hello {name}")
───────────────────────────────────────────────────────────────────────────────
>>> What is this code about?
The snippet of code you've provided is written in Python. It prompts the user...
>>> Follow up questions...Function callingFunction callsis 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 installdefault functionsrun:sgpt--install-functionsShellGPT has a convenient way to define functions and use them. In order to create your custom function, navigate to~/.config/shell_gpt/functionsand create a new .py file with the function name. Inside this file, you can define your function using the following syntax:# execute_shell_command.pyimportsubprocessfrompydanticimportFieldfrominstructorimportOpenAISchemaclassFunction(OpenAISchema):"""Executes a shell command and returns the output (result)."""shell_command:str=Field(...,example="ls -la",descriptions="Shell command to execute.")classConfig:title="execute_shell_command"@classmethoddefexecute(cls,shell_command:str)->str:result=subprocess.run(shell_command.split(),capture_output=True,text=True)returnf"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 thetitleattribute and parameters descriptions. Theexecutefunction 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: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.jsonNote 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 installedjqin our system, and we ask LLM to parse JSON file: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: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 dedicatedcategoryin GitHub Discussions for sharing and discussing functions.
LLM might execute destructive commands, so please use it at your own risk❗️RolesShellGPT 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-roleoption 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/roleswith the role name. Inside this directory, you can also edit defaultsgptroles, such asshell,code, anddefault. Use the--list-rolesoption to list all available roles, and the--show-roleoption to display the details of a specific role. Here's an example of a custom role:sgpt--create-rolejson_generator# Enter role description: Provide only valid json as response.sgpt--rolejson_generator"random: user, password, email, address"{"user":"JohnDoe","password":"p@ssw0rd","email":"johndoe@example.com","address":{"street":"123 Main St","city":"Anytown","state":"CA","zip":"12345"}}If the description of the role contains the words "APPLY MARKDOWN" (case sensitive), then chats will be displayed using markdown formatting.Request cacheControl cache using--cache(default) and--no-cacheoptions. This caching applies for allsgptrequests to OpenAI API: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 thatsgpt "what are the colors of a rainbow" --temperature 0.5will 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 fileYou 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_API_KEY=your_api_key
# Base URL of the backend server. If "default" URL will be resolved based on --model.
API_BASE_URL=default
# Max amount of cached message per chat session.
CHAT_CACHE_LENGTH=100
# Chat cache folder.
CHAT_CACHE_PATH=/tmp/shell_gpt/chat_cache
# Request cache length (amount).
CACHE_LENGTH=100
# Request cache folder.
CACHE_PATH=/tmp/shell_gpt/cache
# Request timeout in seconds.
REQUEST_TIMEOUT=60
# Default OpenAI model to use.
DEFAULT_MODEL=gpt-3.5-turbo
# Default color for shell and code completions.
DEFAULT_COLOR=magenta
# When in --shell mode, default to "Y" for no input.
DEFAULT_EXECUTE_SHELL_CMD=false
# Disable streaming of responses
DISABLE_STREAMING=false
# The pygment theme to view markdown (default/describe role).
CODE_THEME=default
# Path to a directory with functions.
OPENAI_FUNCTIONS_PATH=/Users/user/.config/shell_gpt/functions
# Print output of functions when LLM uses them.
SHOW_FUNCTIONS_OUTPUT=false
# Allows LLM to use functions.
OPENAI_USE_FUNCTIONS=true
# Enforce LiteLLM usage (for local LLMs).
USE_LITELLM=falsePossible options forDEFAULT_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 forCODE_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]     │
│ --md             --no-md                      Prettify markdown output. [default: md]                    │
│ --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.                           │
│ --interaction         --no-interaction    Interactive mode for --shell option. [default: interaction]    │
│ --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.                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯DockerRun the container using theOPENAI_API_KEYenvironment variable, and a docker volume to store cache:dockerrun--rm\--envOPENAI_API_KEY="your OPENAI API key"\--volumegpt-cache:/tmp/shell_gpt\ghcr.io/ther1d/shell_gpt--chatrainbow"what are the colors of a rainbow"Example of a conversation, using an alias and theOPENAI_API_KEYenvironment variable:aliassgpt="docker run --rm --env OPENAI_API_KEY --volume gpt-cache:/tmp/shell_gpt ghcr.io/ther1d/shell_gpt"exportOPENAI_API_KEY="your OPENAI API key"sgpt--chatrainbow"what are the colors of a rainbow"sgpt--chatrainbow"inverse the list of your last answer"sgpt--chatrainbow"translate your last answer in french"You also can use the providedDockerfileto build your own image:dockerbuild-tsgpt.