Skip to content
Get packs

Guide · Open source

How to use shell_gpt: install sgpt and get shell commands from AI

Updated · written with AI from the project's own documentation and checked against our catalogue data

ShellGPT (shell_gpt, run as the sgpt command) is a terminal tool that sends your questions to an AI language model and prints the answer back in your shell. It is aimed at developers and terminal users who often forget command syntax and would rather not search for it online. After this guide you will be able to install it, set up an API key, generate and run shell commands, pass in files or command output, and hold a multi-turn chat session.

ShellGPTTheR1D/shell_gpt · ★ 12.3k · MIT

Quick start

  1. 1Install the package. Run pip install shell-gpt. You need Python on your machine.
  2. 2Add your OpenAI API key. Run sgpt and enter your key when prompted. It is stored in ~/.config/shell_gpt/.sgptrc. Note that OpenAI API usage is not free.
  3. 3Ask a simple question. Run sgpt with a quoted question to confirm it works.
  4. 4Generate a shell command. Run sgpt --shell with a description of the task, then review the command before you press e to execute it.
  5. 5Pipe in some input. Send a file or command output into sgpt with a pipe or redirect and add a prompt describing what to do.
  6. 6Start a chat session. Use --chat with a session name to continue a conversation across several prompts.

Install shell_gpt and set up your API key

ShellGPT is installed with pip, and you need Python. Run the install command, then run sgpt once. You will be prompted for your key, which is stored in ~/.config/shell_gpt/.sgptrc.

By default ShellGPT uses OpenAI's API and the GPT-4 model, so you need an OpenAI API key. The README notes that the OpenAI API is not free of charge, so check OpenAI's pricing page before you start.

  • Requirements: Python and an OpenAI API key (default backend).
  • Supported platforms per the README: Linux, macOS and Windows, with shells such as PowerShell, CMD, Bash and Zsh.
  • Your key is saved to ~/.config/shell_gpt/.sgptrc.
pip install shell-gpt

Ask a question from the command line

Pass your question as a quoted argument to sgpt. The answer is printed to the terminal. This works well for general questions and technical configuration questions.

sgpt "What is the fibonacci sequence"

Pipe files, logs and git diffs into sgpt

ShellGPT accepts input from both stdin and the command line argument. You can pipe command output in and add a prompt that says what to do with it. You can also use redirection operators to pass a file or a here-document.

The README's examples include generating a git commit message from a diff and asking for errors in container logs.

  • Use a pipe to send output to sgpt along with a prompt.
  • Use < to pass a file as input.
  • Use << EOF or <<< for inline multi-line or single-line input.
git diff | sgpt "Generate git commit message, for my changes"

Generate shell commands with --shell

When you forget the syntax of a command such as find, use the --shell or -s option. ShellGPT generates a command and asks what you want to do with it. Press e to execute it, d to get a description, or a to abort.

ShellGPT is aware of your OS and $SHELL, so the same request can return different commands on macOS and Ubuntu. Read every command before you execute it, because the tool offers to run AI-generated commands.

  • Add --no-interaction to print the command to stdout instead of prompting, for example to pipe it into a clipboard tool.
  • Prompts can include shell output, such as $(ls -m), to build a command from real file names.
sgpt --shell "find all json files in current folder"

Generate code and save it to a file

Use --code or -c to request pure code output with no extra prose. You can redirect the result into a file and run it, or pipe an existing file in to ask for changes such as comments.

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

Keep a multi-turn conversation with --chat

Chat mode saves a conversation under a session name you choose, so later prompts can build on earlier answers. Sessions are stored at the CHAT_CACHE_PATH location, which is configurable in the runtime configuration file. You can start a chat with --code or --shell too.

Use the same session name for each follow-up. Use a new name to start a fresh conversation.

  • Choose a unique session name for each separate task.
  • The README also describes a REPL mode, which uses the same chat session object in an interactive loop.
sgpt --chat conversation_1 "please remember my favorite number: 4"

Optional: use shell integration hotkeys

Shell integration lets you use sgpt without typing the prompt each time. It is supported by Bash and Zsh. Run the install command and restart your terminal. The README says this adds a few lines to your .bashrc or .zshrc file.

After installation, Ctrl+l (the default) replaces your current input line with the suggested command. You can edit it, then press Enter to run it.

  • The default hotkey is Ctrl+l.
  • Restart the terminal after installing integration.
sgpt --install-integration

What people use it for

  • Recalling command syntax such as find or tar without leaving the terminal.
  • Drafting a git commit message from git diff output.
  • Scanning container or application logs for errors and possible fixes.
  • Generating a small code file, then adding comments to an existing script.
  • Building up a shell command step by step in a chat session, such as listing files, sorting them, then concatenating them.

Frequently asked questions

Is shell_gpt free to use?

The tool itself is MIT-licensed open source, but by default it uses OpenAI's API, which the README says is not free of charge. You can run open-source models locally for free, but the README notes ShellGPT is not optimized for local models and may not work as expected.

How do I install shell_gpt?

Run pip install shell-gpt. You need Python and an OpenAI API key for the default backend. The README links to the OpenAI key page and pricing page.

Where does shell_gpt store my API key?

You are prompted for your key, and it is stored in ~/.config/shell_gpt/.sgptrc. The README does not describe other storage locations.

Can shell_gpt run commands automatically?

With --shell, it offers choices including [E]xecute, [D]escribe and [A]bort, so you choose whether to run the command. The README warns against running AI-generated commands without reading them first.

Can I use shell_gpt with Ollama or other local models?

The README mentions Ollama as a way to run open-source models locally and links to a separate guide for setting it up with ShellGPT. It also states that ShellGPT is not optimized for local models.

Does shell_gpt work on Windows?

The README says it supports Linux, macOS and Windows, and is compatible with shells such as PowerShell and CMD as well as Bash and Zsh. Shell integration hotkeys are described as supported only in Bash and Zsh.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ShellGPT suits developers and terminal users who often look up command syntax, and who are comfortable paying for OpenAI API usage and reading commands before running them. If you need a graphical interface, want free local models without setup, or will not pay for an API, look at the comparable projects listed for this item, such as aichat, llm, tldr or Warp.

Install options & downloads