ShellGPT CLI
The sgpt command for your terminal: writes shell commands and code, reads piped output, keeps chats and calls functions through OpenAI or a local model
- 12,296 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The --shell mode and function calling let the model suggest and, once you confirm, run any command as your user
- Prompt text and piped data go to the chosen model provider, and the API key is stored in the ~/.config/shell_gpt/.sgptrc file
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/shellgptDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The --shell mode and function calling let the model suggest and, once you confirm, run any command as your user
- Prompt text and piped data go to the chosen model provider, and the API key is stored in the ~/.config/shell_gpt/.sgptrc file
This is third-party code. Review the repository files before installing.
What it does
ShellGPT installs as a Python package and adds the sgpt command to your terminal. You pass a question as an argument or pipe data in, for example git diff for a commit message or the tail of docker logs to find errors. The --shell (-s) flag returns a ready command for your OS and shell and asks whether to execute, describe or abort it. The --code (-c) flag returns plain code with no commentary that you can redirect straight into a file. Conversations are stored under a session name (--chat), and --repl opens an interactive loop that also works with --shell and --code. sgpt --install-integration adds a Ctrl+l hotkey to .bashrc or .zshrc that drops the suggested command into your input line for editing. With function calling the model can reach scripts you keep in ~/.config/shell_gpt/functions, and custom roles set the system prompt.
Who it is for. For developers and sysadmins who would rather not look up find, ffmpeg or docker syntax in a browser and are ready to confirm each command before it runs.
Good fit when
- You need to recall a command's syntax: sgpt -s "find all json files in current folder" returns find . -type f -name "*.json" and asks before running it
- You want a commit message from the current changes: git diff | sgpt "Generate git commit message, for my changes"
- A container log needs a quick triage: docker logs -n 20 my_app | sgpt "check logs, find errors, provide possible solutions"
- A command takes several refinements, and --chat with one session name lets you adjust the result until it fits
- You want suggestions right in the terminal input line on Ctrl+l without typing sgpt
Not a fit when
- You need an agent that edits project files and runs tests on its own: sgpt answers requests and does not run multi-step repository work
- You plan to run local models and expect stability: the developer warns that ShellGPT is not optimized for them and may not work as expected
- Functions are enabled and the model has broad rights: it may run a destructive command, and the developer advises using functions on your own responsibility
- Python 3.10 or newer is missing and you cannot install it or run a container
Example request
Install ShellGPT, run sgpt -s "compress every png in the current folder" and show me the command before it runsLimitations
- By default ShellGPT uses the OpenAI API and asks for a key on first run; the key is stored in ~/.config/shell_gpt/.sgptrc. The API is paid. It is not reachable from Russia without extra means, so set your own API_BASE_URL or use a local model.
- A guide for local models through Ollama is in the repository wiki, but the developer notes the tool is not optimized for them.
- Function calling is on by default; the --no-functions flag turns it off.
- Python 3.10 or newer is required. A Docker image is available.
How to disable. Remove the package with pip uninstall shell-gpt. If you installed the shell integration, delete the lines it added to .bashrc or .zshrc. Settings and the key live in ~/.config/shell_gpt, and chat history is kept in the chat_cache folder.
FAQ
How do I install ShellGPT and add my key?
Run pip install shell-gpt. On first launch sgpt asks for an OpenAI key and stores it in ~/.config/shell_gpt/.sgptrc. The same file holds API_BASE_URL, DEFAULT_MODEL and DEFAULT_EXECUTE_SHELL_CMD.
How do I make sgpt return only a command?
Use sgpt --shell or -s. With --no-interaction the command goes to stdout without a prompt, so you can pipe it onward, for example to pbcopy.
Can ShellGPT work with a local Ollama model?
Yes. The repository wiki has an Ollama guide, and API_BASE_URL is set in .sgptrc. The developer warns that ShellGPT is not optimized for local models and results may vary.
How do I run ShellGPT in Docker?
Run the ghcr.io/ther1d/shell_gpt container with the OPENAI_API_KEY variable and a cache volume. OS_NAME and SHELL_NAME tell the model about your system and shell. You can also build the image yourself from the Dockerfile with docker build -t sgpt .
How do I add my own functions to sgpt?
sgpt --install-functions installs the defaults such as execute_shell_command. Custom functions are separate .py files in ~/.config/shell_gpt/functions. The class docstring goes to the model as the function description.
Discussion
No questions or reviews yet.
Related
CLI toolsA spec-driven delivery skill: PRDs, epics, tasks, GitHub Issues sync and parallel agents in git worktrees
A desktop pet that reacts to Claude Code, OpenCode and Cursor through hooks and MCP without putting code, paths or secrets in its speech
ChatGPT Shortcut
chatgpt-shortcut
A library of ready prompts with search, favorites and the AiShort browser extension. The interface is mostly in Chinese
A Go CLI that keeps skills, agents and rules in one place and syncs them into every AI agent with one command
Pachca API skills and CLI
Пачка API
Official agent skills and CLI for the Pachca corporate messenger: messages, chats, users, bots, tasks and search
Official Todoist command line with an agent skill: tasks, projects and inbox from the terminal
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| ShellGPT (this entry) | no | 12,296 | |
| Fabric | no | 44,485 | a library of ready prompt patterns for tasks such as summaries and analysis, while sgpt targets terminal commands and code |
| Aider | no | 49,803 | edits repository files and commits on its own, while sgpt only answers in the terminal |
| Magic CLI | no | 745 | rust command-line tool that suggests shell commands from a description |
README in short
The front page starts with a pip install and notes on the OpenAI key and on local models. Examples follow in order: requests through arguments and pipes, shell command generation, Bash and Zsh integration, code mode, chats, REPL, function calling and roles. Near the end come the settings file, the full list of command-line arguments, running in Docker and links to the Azure and Ollama guides.