ShellGPT

ShellGPT supports persistent conversations using chat sessions. Each session is stored in the CHAT_CACHE_PATH (configurable). You can use the same session ID to iteratively improve suggestions or add context.

• --chat <session_id>: Start or continue a conversation with a specific ID. Use temp for a quick session.
• --list-chats or -lc: List all existing chat sessions.
• --show-chat <session_id>: Display the full message history of a specific session.

# Start a new conversation
sgpt --chat conversation_1 "please remember my favorite number: 4"

# Continue the same conversation
sgpt --chat conversation_1 "what would be my favorite number + 4?"

# List all sessions
sgpt --list-chats

# View history of a session
sgpt --show-chat conversation_1

The REPL (Read-Eval-Print Loop) mode allows for an interactive, continuous chat session.

• Use --repl <session_name> to start. Use temp for a non-persistent session.
• If used with --shell, it enters a shell REPL where you can type e to execute a suggested command or d to describe it.
• For multiline prompts, wrap your text in triple quotes """.
• You can pipe files into REPL mode to start a conversation about specific content.

# Start a standard REPL session
sgpt --repl temp

# Start a shell-specific REPL session
sgpt --repl temp --shell

# Start REPL with file content via stdin
sgpt --repl temp < my_app.py

Install the ShellGPT command-line tool using pip. This tool provides AI-powered generation of shell commands, code snippets, and documentation across Linux, macOS, Windows, and major shells (PowerShell, CMD, Bash, Zsh).

pip install shell-gpt

Shell integration allows you to invoke ShellGPT using terminal hotkeys (e.g., Ctrl+l) in Bash or ZSH. This injects suggested commands directly into your terminal buffer for immediate editing and execution.

To install, run:

sgpt --install-integration

Then, restart your terminal to apply the changes to your .bashrc or .zshrc.

You can run ShellGPT inside a Docker container. To ensure persistence, use a Docker volume to store the cache at /tmp/shell_gpt. It is recommended to pass OS_NAME and SHELL_NAME environment variables so the AI understands your environment context. The OPENAI_API_KEY must be provided via an environment variable.

docker run --rm \
           --env OPENAI_API_KEY=api_key \
           --env OS_NAME=$(uname -s) \
           --env SHELL_NAME=$(echo $SHELL) \
           --volume gpt-cache:/tmp/shell_gpt \
       ghcr.io/ther1d/shell_gpt -s "update my system"

You can run open-source models locally for free by setting up an LLM backend like Ollama.

Warning: ShellGPT is not specifically optimized for local models and behavior may vary from the default OpenAI integration. For specific configuration steps, refer to the Ollama guide.

ShellGPT supports OpenAI function calling, allowing the LLM to execute system functions.

1. Install default functions: Run sgpt --install-functions.
2. Custom functions: Create a .py file in ~/.config/shell_gpt/functions/. The class docstring, title attribute, and parameter descriptions are used to inform the LLM. The execute method is called when the LLM triggers the function.
3. Usage: The LLM will output @FunctionCall function_name(...) when it decides to use a tool.

# Install default functions
sgpt --install-functions

# Example of LLM triggering a function
sgpt "What are the files in /tmp folder?"
# -> @FunctionCall execute_shell_command(shell_command="ls /tmp")

By default, ShellGPT uses OpenAI's API and the GPT-4 model.

1. Generate an API key from the OpenAI platform.
2. Run ShellGPT; you will be prompted to enter your API key.
3. The key is stored locally in ~/.config/shell_gpt/.sgptrc for future use.

Note: OpenAI API usage incurs costs based on OpenAI pricing.

If you prefer to manage your own image instead of using the one from ghcr.io, you can build one locally using the provided Dockerfile in the repository.

docker build -t sgpt .

Runtime parameters can be set in ~/.config/shell_gpt/.sgptrc. Key configuration options include:

When using the --shell option with --interaction enabled, ShellGPT enters a loop that allows you to manage the generated command before it is executed. After a command is generated, you are presented with the following choices:

• [E]xecute / [Y]es: Run the generated command in your shell.
• [M]odify: Edit the generated command using a prompt session (allowing you to refine the command).
• [D]escribe: Instead of running the command, use the DESCRIBE_SHELL role to explain what the command does.
• [A]bort: Exit the process without executing the command.

ShellGPT supports persistent chat sessions and custom system roles to guide the model's behavior.

Chat Management

• Continue a session: Use --chat <session_id> to append your prompt to an existing conversation.
• List sessions: Use --list-chats to see all available chat IDs.
• View history: Use --show-chat <session_id> to inspect the messages within a specific chat.

Role Management

Roles act as system prompts that define the persona or constraints of the LLM.

• List roles: Use --list-roles to see available roles.
• Create a role: Use --create-role <name> to define a new system role.
• Use a role: Use --role <name> to apply a specific role to your current prompt.