Purpose
ShellGPT is a command-line productivity tool powered by AI large language models (LLMs). It is designed to help users complete tasks faster and more efficiently. Its main uses include generating Shell commands, code snippets, and documentation, reducing reliance on external resources (such as search engines).
Main Capabilities
- Generate Shell commands: Through the --shell or -s option, it can quickly generate and execute the required command based on the user's description. ShellGPT is aware of the operating system and the currently used $SHELL, thereby providing commands adapted to the specific system.
- Generate code: Through the --code or -c option, request pure code output, and the output can be redirected to a file.
- Sessions and REPL: Supports chat mode (--chat) and REPL mode (--repl), and sessions are saved in the configurable CHAT_CACHE_PATH. You can use --list-chats to list sessions and --show-chat to view session messages.
- Function calling: The function calling capability provided by OpenAI allows the LLM to execute functions in the user's system. You can install default functions, or create custom .py files in ~/.config/shell_gpt/functions. The docstring in the class is passed to the OpenAI API as the function description.
- Custom roles: Use --create-role to create roles. Role files are saved in ~/.config/shell_gpt/roles, and can be managed with --list-roles and --show-role. If the role description contains "APPLY MARKDOWN", the chat will be displayed in Markdown format.
- Cache control: Use --cache (default) and --no-cache to control request caching. The same query will hit the local cache, but if parameters such as --temperature or --top-probability are changed, a new request will be made.
- Shell integration: After running sgpt --install-integration and restarting the terminal, you can add the relevant configuration to .bashrc or .zshrc. By default, Ctrl+l is used to invoke ShellGPT and place the suggested command directly into the terminal input line, making it easy to edit and then press Enter to execute.
Usage
ShellGPT accepts prompts from standard input (stdin) and command-line arguments. Input can be passed through a pipe, for example to generate a git commit message based on a diff, or to pass logs for analysis and obtain errors and suggestions. Use the --no-interaction option to disable interactive mode and output the generated command directly to stdout, making it easy to copy to the clipboard through a pipe and other operations.
The runtime configuration file is located at ~/.config/shell_gpt/.sgptrc, where you can set DEFAULT_COLOR (black, red, green, yellow, blue, magenta, cyan, white, and the bright_ series, etc.), CODE_THEME (refer to the pygments style links), MARKDOWN_LIVE_VERTICAL_OVERFLOW (ellipsis, visible, crop). The default ellipsis mode only shows "..." when the Markdown output exceeds the terminal height; visible mode (recommended for REPL sessions) can display all generated content in real time.
Docker usage: Run the container through the OPENAI_API_KEY environment variable and a docker volume for storing the cache. You can set the OS_NAME and SHELL_NAME environment variables according to your preference. You can also use the provided Dockerfile to build the image yourself.
Applicable Scenarios
Suitable for quickly analyzing and retrieving information in the terminal, handling various direct requests ranging from technical configuration to general knowledge. It can be used to generate git commit messages, analyze logs, find and execute Shell commands, generate code, conduct multi-turn conversations to iteratively improve suggestions, and more.
Limitations
By default, it relies on the OpenAI API and the GPT-4 model, requires an API key, and the OpenAI API is not free. If running an open-source model locally, you need to set up an LLM backend yourself (such as Ollama), and ShellGPT is not optimized for local models and may not work as expected. The LLM may execute destructive commands, so use it at your own risk.
