◆ AI Coding Agents

shell-gpt

1.5.0 open-source

sgpt --install-functions
USE_LITELLM=true
sgpt --no-md 'List the top 5 open ports on a Linux server'
API_BASE_URL=https://my-llm-proxy.internal/v1
sgpt --repl temp < my_app.py
sgpt --install-functions
OPENAI_FUNCTIONS_PATH=/home/user/.config/sgpt/functions
OPENAI_USE_FUNCTIONS=true
SHOW_FUNCTIONS_OUTPUT=true
CODE_THEME=monokai
sgpt --repl temp
>>> """
... Write a bash script that monitors disk usage
... and sends an alert if usage exceeds 80%
... """
sgpt --model gpt-3.5-turbo-16k "16k context prompt"
pip install --upgrade shell-gpt
sgpt --install-integration
# Restart your terminal, then type a natural-language request and press Ctrl+l to get a command suggestion.
DEFAULT_EXECUTE_SHELL_CMD=true
sgpt -s --repl temp
# >>> list running containers
# docker ps
# >>> d
# Lists all currently running Docker containers.
# >>> e
sgpt --create-role json
# Enter role description: You are JSON generator, provide only valid json as response.
# Enter expecting result, e.g. answer, code, shell command, etc.: json
sgpt --role json "random: user, password, email, address"
git diff | sgpt "Generate git commit message, for my changes"
DEFAULT_COLOR=magenta
sgpt --repl my-session --shell
sgpt --repl my-session
sgpt --shell 'list all open ports on this machine'

Summary

shell-gpt is an open-source command-line tool that turns natural-language prompts into shell commands, code snippets, and documentation, letting you skip searching the web while working in the terminal. It is free itself, though by default it calls OpenAI's API with your own key, which is billed separately; it can also be pointed at LiteLLM-compatible backends or run against local models via Ollama, though the README warns it isn't tuned for those. Installed with pip and invoked as `sgpt`, it works across Linux, macOS, and Windows shells, and suits developers who want command generation, log analysis, or commit-message drafting without leaving the CLI. It fits alongside other AI coding-agent tools rather than any named competitor. First committed in 2023 with 44 contributors, it has slowed to 13 commits in the past year, with its last release 107 days ago.

What shell-gpt answers

Does it run a generated command automatically, or let me check it first?

shows the proposed command and lets me edit it in place before anything executes

Will switching to a local model give me the same experience as the default setup?

not according to the project itself, which warns local models aren't tuned and behavior may fall short of the OpenAI-backed default

Does it remember context across multiple questions, or treat each one separately?

a named chat session persists context, while a one-off invocation does not

Command line

composed command

option surface across analysed releases

options at that release added, per release removed, per release

option	found in	since	description

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1.5.0 Jan 28, 2026 · issue -201

shell-gpt 1.5.0 lets you edit AI-generated shell commands before execution and drops the instructor dependency.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.5.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.5.0
```
└──▷ TRY IT
Restore function-calling support after upgrading, required because the instructor package was removed.
```
$ sgpt --install-functions
```
- ›Adds ability to modify a generated shell command before running it, letting you tweak AI output in-place rather than accepting or rejecting wholesale.
└──▷ BREAKING ON UPGRADE
- !The instructor package has been removed from dependencies; users who relied on function calling must re-run sgpt --install-functions to reinstall default functions and manually update any custom functions.
1.4.5 Apr 8, 2025 · issue -367

shell-gpt 1.4.5 adds LiteLLM support, unlocking hundreds of additional AI model backends.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.4.5 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.4.5
```
- ›Supports all LiteLLM-compatible models, enabling use of any backend provider LiteLLM supports (e.g., Azure, Anthropic, Cohere, and more).
1.4.4 Aug 10, 2024 · issue -375

shell-gpt 1.4.4 enables function calling on Groq and other non-OpenAI models, and switches the default model to gpt-4o.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.4.4 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.4.4
```
- ›Supports function calling on Groq and other compatible models via the new OpenAI function-calling format.
- ›Changes the default model to gpt-4o for all interactions.
└──▷ BREAKING ON UPGRADE
- !The default model is changed to gpt-4o; existing setups that relied on the previous default model will now use gpt-4o unless overridden in configuration.
1.4.3 Apr 6, 2024 · issue -379

shell-gpt 1.4.3 adds Ctrl+C interruption of streaming LLM responses in REPL mode
└──▷ GET THIS VERSION
```
$ git clone --branch 1.4.3 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.4.3
```
- ›Adds Ctrl+C interruption support to cancel an actively streaming LLM response while in REPL mode.
1.4.0 Feb 22, 2024 · issue -381

shell-gpt 1.4.0 adds LiteLLM multi-backend support and per-run markdown control via new flags and config keys.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.4.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.4.0
```
└──▷ USE IT
Route a prompt through a non-OpenAI LLM backend (e.g. Anthropic, Cohere) by enabling LiteLLM in the config.
ini
```
USE_LITELLM=true
```
Suppress markdown rendering for a single call when piping output to another tool.
```
$ sgpt --no-md 'List the top 5 open ports on a Linux server'
```
- ›Adds --md and --no-md CLI flags to enable or disable markdown output on a per-invocation basis.
- ›Adds PRETTIFY_MARKDOWN config key in ~/.config/shell_gpt/.sgptrc to set the default markdown rendering behavior.
- ›Adds USE_LITELLM config key in ~/.config/shell_gpt/.sgptrc to enforce LiteLLM as the request backend, unlocking support for numerous non-OpenAI LLM providers; install via pip install shell-gpt[litellm].
1.3.1 Feb 17, 2024 · issue -381

shell-gpt 1.3.1 adds API_BASE_URL config variable to point at custom OpenAI-compatible endpoints.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.3.1 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.3.1
```
└──▷ TRY IT
Point shell-gpt at a self-hosted or proxy LLM endpoint instead of the default OpenAI API.
```
$ API_BASE_URL=https://my-llm-proxy.internal/v1
```
- ›Adds API_BASE_URL config variable to redirect shell-gpt to any OpenAI-compatible API base, enabling use with self-hosted or alternative LLM endpoints.
1.3.0 Feb 9, 2024 · issue -381

shell-gpt 1.3.0 adds multi-backend LLM support via LiteLLM (including Ollama) and role-driven Markdown formatting control.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.3.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.3.0
```
- ›Supports multiple LLM backends via LiteLLM, enabling locally hosted open-source models such as Ollama alongside existing cloud providers.
- ›Controls Markdown formatting per role: including "APPLY MARKDOWN" in a role's description enables formatted output; removing it disables it for that role.
- ›Allows editing the default role description at ~/.config/shell_gpt/roles to globally enable or disable Markdown formatting.
1.2.0 Jan 28, 2024 · issue -382

shell-gpt 1.2.0 adds --no-interaction flag for redirectable shell output and stdin support in REPL mode.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.2.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.2.0
```
└──▷ TRY IT
Seed a REPL session with a source file as context, then ask follow-up questions interactively.
```
$ sgpt --repl temp < my_app.py
```
- ›Adds --no-interaction flag (used with --shell) to print the suggested command to stdout instead of interactive mode, enabling shell pipeline use like sgpt -s "say hi" | pbcopy.
- ›REPL mode now accepts stdin, a PROMPT argument, or both simultaneously, allowing initial context to be piped in alongside an interactive session.
└──▷ BREAKING ON UPGRADE
- !Shell integration in ~/.bashrc or ~/.zshrc will stop working on upgrade; run sgpt --install-integration and manually remove the old integration function from your shell profile.
1.1.0 Jan 9, 2024 · issue -382

shell-gpt 1.1.0 adds OpenAI function calling, letting the LLM execute shell commands and AppleScripts via new --install-functions and --functions flags.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.1.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.1.0
```
└──▷ TRY IT
Install default functions so the LLM can run shell commands and AppleScripts on your machine.
```
$ sgpt --install-functions
```
Point shell-gpt at a custom functions directory and enable function calling by default in your config.
ini
```
OPENAI_FUNCTIONS_PATH=/home/user/.config/sgpt/functions
OPENAI_USE_FUNCTIONS=true
SHOW_FUNCTIONS_OUTPUT=true
```
- ›Adds --install-functions flag to download and install default functions, enabling the LLM to execute shell commands and AppleScripts (macOS) directly on your system.
- ›Adds --functions flag to enable or disable OpenAI function calling at invocation time.
- ›Adds OPENAI_FUNCTIONS_PATH config variable to specify the directory where custom function definitions are loaded from.
- ›Adds OPENAI_USE_FUNCTIONS config variable to enable or disable function calling globally in the config.
- ›Adds SHOW_FUNCTIONS_OUTPUT config variable to control whether function execution output is displayed.
+2 moreshow less
- ›Adds shortcut -c as an alias for --code, -lc for --list-chats, and -lr for --list-roles.
- ›Integrates the OpenAI Python library for API requests, providing more descriptive error messages with suggested solutions.
1.0.0 Dec 20, 2023 · issue -383

ShellGPT 1.0.0 adds GPT-4 Turbo as default, markdown rendering, CODE_THEME config, multiline REPL input, and --version flag.
└──▷ GET THIS VERSION
```
$ git clone --branch 1.0.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 1.0.0
```
└──▷ USE IT
Set CODE_THEME in the ShellGPT config file to customise markdown syntax highlighting.
ini
```
CODE_THEME=monokai
```
Enter a multiline prompt in REPL mode to compose complex instructions without leaving the session.
```
$ sgpt --repl temp
>>> """
... Write a bash script that monitors disk usage
... and sends an alert if usage exceeds 80%
... """
```
- ›New CODE_THEME config variable in ~/.config/shell_gpt/.sgptrc sets the syntax-highlighting theme for markdown output (default: dracula).
- ›Adds --version flag to print the installed ShellGPT version.
- ›Multiline input in REPL mode now supported using """ triple-quote delimiters.
- ›Default model switched to gpt-4-1106-preview (GPT-4 Turbo) in ~/.config/shell_gpt/.sgptrc.
- ›Renders markdown for default and 'describe shell command' outputs.
+1 moreshow less
- ›Roles (prompts) optimised for OpenAI GPT-4 models using system roles via the OpenAI chat messages API.
└──▷ BREAKING ON UPGRADE
- !Previously created custom roles and chats are incompatible with v1.0.0 and must be re-created using the new version.
- !The DEFAULT_MODEL value in ~/.config/shell_gpt/.sgptrc should be updated to gpt-4-1106-preview; older models may not perform correctly with the new system roles.
0.9.4 Jul 19, 2023 · issue -388

shell-gpt 0.9.4 lets you point --model at any OpenAI-compatible local API, enabling air-gapped LLM usage.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.9.4 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.9.4
```
- ›Changes --model from an enum to a free-form string, allowing it to accept any model name including those served by self-hosted, OpenAI-compatible endpoints such as LocalAI.
- ›Supports locally hosted language models via any OpenAI-compatible API server (e.g. LocalAI), enabling offline or cost-free LLM usage on your own hardware.
└──▷ BREAKING ON UPGRADE
- !The --model parameter type changed from an enum to a string; any tooling or scripts that relied on enum validation of --model values should be verified for compatibility.
0.9.3 Jun 14, 2023 · issue -389

shell-gpt 0.9.3 adds support for gpt-3.5-turbo-16k, giving 4× the context window of the standard model.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.9.3 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.9.3
```
└──▷ TRY IT
Send a long prompt or paste a large file's contents into sgpt using the 16k-token context model to avoid truncation.
```
$ sgpt --model gpt-3.5-turbo-16k "16k context prompt"
```
- ›Adds support for --model gpt-3.5-turbo-16k, enabling 4× the context of gpt-3.5-turbo (16k tokens) for longer prompts and conversations.
0.9.2 Jun 4, 2023 · issue -389

shell-gpt 0.9.2 adds ZSH and Bash shell integration with hotkey-triggered command suggestions via --install-integration.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.9.2 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.9.2
```
└──▷ TRY IT
Install the shell integration once so that Ctrl+l triggers GPT command suggestions from any terminal prompt.
```
$ pip install --upgrade shell-gpt
sgpt --install-integration
# Restart your terminal, then type a natural-language request and press Ctrl+l to get a command suggestion.
```
- ›Adds --install-integration hidden flag to automatically update the user's shell profile and enable shell integration for ZSH and Bash.
- ›New shell integration for ZSH and Bash lets users press Ctrl+l in the terminal to replace the current input buffer with an sgpt-suggested shell command.
- ›Shell integration surfaces sgpt completions inside shell history and allows immediate in-line editing of suggested commands.
0.9.1 May 21, 2023 · issue -390

shell-gpt 0.9.1 adds --describe-shell flag, in-prompt describe option, and DEFAULT_EXECUTE_SHELL_CMD config key
└──▷ GET THIS VERSION
```
$ git clone --branch 0.9.1 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.9.1
```
└──▷ USE IT
Auto-execute shell suggestions on Enter in CI or scripting workflows without typing 'e' each time.
ini
```
DEFAULT_EXECUTE_SHELL_CMD=true
```
Inspect a suggested command interactively before running it during a shell REPL session.
```
$ sgpt -s --repl temp
# >>> list running containers
# docker ps
# >>> d
# Lists all currently running Docker containers.
# >>> e
```
- ›Adds --describe-shell (or -d) CLI flag to generate a natural-language explanation of any shell command, e.g. sgpt -d "ls -la".
- ›Adds DEFAULT_EXECUTE_SHELL_CMD config parameter to .sgptrc (default false); set to true to auto-execute --shell suggestions on Enter without typing e.
- ›Adds [D]escribe option to the --shell execution prompt, letting users get an inline explanation of a suggested command before deciding to execute or abort.
- ›Adds [d] describe shortcut inside --repl shell mode, printing an explanation of the last suggested command before execution.
- ›Raises the maximum allowed value of --temperature to 2.
+1 moreshow less
- ›Excludes comment lines (lines starting with #) when parsing .sgptrc, enabling inline documentation in the config file.
0.9.0 Apr 16, 2023 · issue -391

shell-gpt 0.9.0 adds custom user-defined roles with --create-role, --list-roles, and --show-role flags.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.9.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.9.0
```
└──▷ TRY IT
Create a reusable 'json' role so every prompt returns only valid JSON — useful for piping structured data into other tools.
```
$ sgpt --create-role json
# Enter role description: You are JSON generator, provide only valid json as response.
# Enter expecting result, e.g. answer, code, shell command, etc.: json
sgpt --role json "random: user, password, email, address"
```
- ›Adds --create-role <name> flag to define custom roles stored as JSON files in ~/.config/shell_gpt/roles, each specifying a system prompt and expected output type (answer, code, shell command, etc.).
- ›Adds --role <name> flag to invoke any custom or built-in role when running a prompt.
- ›Adds --list-roles flag to display all available roles, including user-created and built-in ones.
- ›Adds --show-role <name> flag to display the details of a specific role.
- ›Allows overriding the built-in shell, code, and default roles by editing their JSON files in ~/.config/shell_gpt/roles.
+2 moreshow less
- ›Adds option to force the use of system role messages via a dedicated flag (not recommended by the project).
- ›Improves stdin-plus-prompt handling, e.g. echo hello | sgpt "another hello".
└──▷ BREAKING ON UPGRADE
- !All chats created with previous versions of ShellGPT are incompatible with 0.9.0 and will not work after upgrading.
- !The --list-chat flag is renamed to --list-chats; any scripts or aliases using --list-chat will break.
0.8.8 Apr 10, 2023 · issue -391

shell-gpt 0.8.8 lets you combine stdin piping and a command-line prompt in a single invocation.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.8.8 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.8.8
```
└──▷ TRY IT
Generate a git commit message by piping a diff into sgpt alongside an explicit prompt — no temp files needed.
```
$ git diff | sgpt "Generate git commit message, for my changes"
```
- ›Accepts a prompt from both stdin and a command-line argument simultaneously, enabling piped output to be combined with an inline instruction in one command.
0.8.7 Apr 10, 2023 · issue -391

shell-gpt 0.8.7 adds DEFAULT_COLOR config key to control OpenAI completion output color in the terminal.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.8.7 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.8.7
```
└──▷ USE IT
Set completion output to magenta so AI responses are visually distinct from your own shell output.
ini
```
DEFAULT_COLOR=magenta
```
- ›Adds DEFAULT_COLOR to ~/.config/shell_gpt/.sgptrc (or $DEFAULT_COLOR env var) to set the terminal color of OpenAI completions; supported values: black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white.
0.8.5 Apr 7, 2023 · issue -391

shell-gpt 0.8.5 executes commands in the user's native $SHELL and improves Windows PowerShell and CMD integration.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.8.5 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.8.5
```
- ›Executes generated commands in the user's native $SHELL instead of always defaulting to /bin/sh.
- ›Improves integration with PowerShell and CMD on Windows.
0.8.3 Apr 3, 2023 · issue -391

shell-gpt 0.8.3 adds an interactive REPL mode for chat sessions via --repl, compatible with --shell and --code.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.8.3 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.8.3
```
└──▷ TRY IT
Start an interactive shell-command session in REPL mode to iteratively build and refine commands without re-invoking sgpt each time.
```
$ sgpt --repl my-session --shell
```
Pick up an existing chat session inside REPL mode to continue a conversation with full history displayed.
```
$ sgpt --repl my-session
```
- ›Adds --repl <session-name> option to start an interactive REPL mode for chat sessions, showing conversation history on entry; accepts temp as a session name for a throwaway session.
- ›REPL mode shares sessions with --chat, allowing seamless hand-off between the two modes mid-conversation.
- ›REPL mode supports --shell and --code flags for interactive shell command generation and code generation within the same session.
0.8.0 Mar 28, 2023 · issue -392

shell-gpt 0.8.0 adds streaming OpenAI responses and makes --shell prompt for execution by default.
└──▷ GET THIS VERSION
```
$ git clone --branch 0.8.0 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.8.0
```
└──▷ TRY IT
Generate a shell command and be prompted to execute it immediately, without needing the now-removed --execute flag.
```
$ sgpt --shell 'list all open ports on this machine'
```
- ›Adds streaming responses from the OpenAI API, eliminating the loading spinner and request preloads.
- ›The --shell flag now prompts for execution by default, replacing the separate --execute option.
- ›Improved prompt engineering delivers more accurate suggestions when using --shell and --code flags.
└──▷ BREAKING ON UPGRADE
- !The --execute option has been removed; execution prompting is now built into --shell by default.
0.7.1 Mar 15, 2023 · issue -392

shell-gpt 0.7.1 adds OS and shell detection so suggestions are tailored to your environment
└──▷ GET THIS VERSION
```
$ git clone --branch 0.7.1 https://github.com/TheR1D/shell_gpt.git
# already have the repo? check out this version:
$ git checkout 0.7.1
```
- ›Adds system recognition so sgpt generates suggestions based on your OS and $SHELL environment variable.
- ›Improves prompt engineering for more accurate suggestions.

shell-gpt

Summary

What shell-gpt answers

Examples

Command line

Release history