ShellGPT - AI-powered CLI productivity tool

Language: Python (3.10+)
License: MIT
Stars: ~12,000
Owner: TheR1D
Repo: https://github.com/TheR1D/shell_gpt

Core Dependencies:
- openai (2.x) - LLM API integration
- typer - CLI framework
- rich - Terminal output formatting
- prompt_toolkit - Interactive REPL mode
- litellm (optional) - Local LLM support

pip install shell-gpt

# Install Ollama
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2
ollama pull mistral

# Configure ShellGPT for Ollama - edit ~/.config/shell_gpt/.sgptrc:
USE_LITELLM=true
DEFAULT_MODEL=llama3.2
API_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama

# Quick query
sgpt "What is the fibonacci sequence"

# Pipe input from another command
git diff | sgpt "Generate git commit message for my changes"

# Read from file
sgpt "summarise" < document.txt

# Here document input
sgpt << EOF
What is the best way to learn Golang?
Provide simple hello world example.
EOF

# Find files
sgpt --shell "find all json files in current folder"
# Generates: find . -type f -name "*.json"
# Then prompts: [E]xecute, [D]escribe, [A]bort

# System update (OS-aware)
sgpt -s "update my system"
# macOS: sudo softwareupdate -i -a
# Ubuntu: sudo apt update && sudo apt upgrade -y

# Docker commands
sgpt -s "start nginx container, mount ./index.html"

# Without interactive prompt (pipe the command)
sgpt -s "find all json files in current folder" --no-interaction | pbcopy

# Generate code directly
sgpt --code "solve fizz buzz problem using python"

# Redirect to file and execute
sgpt --code "solve fizz buzz problem" > fizz_buzz.py
python fizz_buzz.py

# Add comments to existing code
cat fizz_buzz.py | sgpt --code "Generate comments for each line"

# Analyze Docker logs
docker logs -n 20 my_app | sgpt "check logs, find errors, provide possible solutions"

# Analyze JSON
cat data.json | sgpt --code "parse this JSON and extract the email field"

# Install shell integration
sgpt --install-integration

# Restart terminal, then use Ctrl+L to invoke ShellGPT
# The generated command replaces your current input line

# Start a new chat session
sgpt --chat my_session "remember my favorite number: 4"
sgpt --chat my_session "what is my favorite number + 4?"

# Chat with code generation
sgpt --chat coding_session --code "make a request to localhost using python"
sgpt --chat coding_session --code "add caching to the request"

# List all chat sessions
sgpt --list-chats

# Show chat history
sgpt --show-chat my_session

# Start REPL
sgpt --repl temp

# Start REPL with shell mode
sgpt --repl temp --shell

# Start REPL with code mode
sgpt --repl temp --code

# Feed file content into REPL
sgpt --repl temp < my_app.py

# Use triple quotes for multiline input in REPL
>>> """
... Explain following code:
... print('hello')
... """

# Install built-in functions
sgpt --install-functions

# Use functions automatically (if enabled)
sgpt "What files are in /tmp folder?"
# LLM executes: ls /tmp

# Chain multiple functions
sgpt "Play music and open hacker news"
# Executes: play_music() + open_url(url="https://news.ycombinator.com")

# Create a new role
sgpt --create-role json_generator
# Enter role description: Provide only valid JSON as response.

# List roles
sgpt --list-roles

# Show a role
sgpt --show-role json_generator

# Use a role
sgpt --role json_generator "create user object with password, email, address"

# API Configuration
OPENAI_API_KEY=***                    # Also accepts OPENAI_API_KEY env var
API_BASE_URL=default                  # Use 'default' or custom URL

# Model
DEFAULT_MODEL=gpt-5.4-mini            # OpenAI model (or Ollama model with USE_LITELLM=true)

# Caching
CHAT_CACHE_LENGTH=100                 # Max messages per chat session
CHAT_CACHE_PATH=/tmp/shell_gpt/chat_cache
CACHE_LENGTH=100                      # Request cache size
CACHE_PATH=/tmp/shell_gpt/cache

# Request
REQUEST_TIMEOUT=60                    # Timeout in seconds
DISABLE_STREAMING=false

# Output
DEFAULT_COLOR=magenta                 # Shell/code output color
CODE_THEME=default                    # Pygments theme for markdown

# Shell Execution
DEFAULT_EXECUTE_SHELL_CMD=false       # Default answer for shell execution prompt

# Functions
OPENAI_USE_FUNCTIONS=true             # Enable function calling
OPENAI_FUNCTIONS_PATH=~/.config/shell_gpt/functions
SHOW_FUNCTIONS_OUTPUT=false           # Show function output in response

# Local LLM Support
USE_LITELLM=false                     # Enable for Ollama/local backends

Main Options:
  --model TEXT          LLM to use [default: gpt-5.4-mini]
  --temperature FLOAT   Randomness [0.0-2.0, default: 0.0]
  --top-p FLOAT         Top-p sampling [0.0-1.0, default: 1.0]
  --md/--no-md          Enable/disable markdown formatting
  --editor              Open $EDITOR for prompt input
  --cache/--no-cache    Enable/disable caching

Assistance Options:
  -s, --shell           Generate and execute shell commands
  --no-interaction      Disable interactive mode for --shell
  -d, --describe-shell  Describe a shell command
  -c, --code            Generate pure code output
  --functions/--no-functions  Enable/disable function calling

Chat Options:
  --chat TEXT           Persistent chat session
  --repl TEXT           Interactive REPL mode
  --show-chat TEXT      Display chat history
  --list-chats, -lc     List all chat sessions

Role Options:
  --role TEXT           Use specific role
  --create-role TEXT    Create new role
  --show-role TEXT      Display role details
  --list-roles, -lr     List all roles

# Run with environment variable
docker run --rm \
           --env OPENAI_API_KEY=your_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"

# Create an alias for convenience
alias sgpt='docker run --rm --volume gpt-cache:/tmp/shell_gpt --env OPENAI_API_KEY --env OS_NAME=$(uname -s) --env SHELL_NAME=$(echo $SHELL) ghcr.io/ther1d/shell_gpt'

# Build your own image
docker build -t sgpt .

# Use with chat session for persistent context
sgpt --chat rainbow "what are the colors of a rainbow"
sgpt --chat rainbow "translate your last answer in french"

1. Direct queries: sgpt "your question"
2. Shell command generation: sgpt -s "command description"
3. Code generation: sgpt -c "program description"
4. stdin piping: cat file | sgpt "analyze"
5. Chat sessions: sgpt --chat name "message"
6. REPL mode: sgpt --repl temp
7. Custom roles: sgpt --role name "prompt"
8. Function calling: sgpt --install-functions
9. Shell hotkey: sgpt --install-integration (Ctrl+L)
10. Docker container: ghcr.io/ther1d/shell_gpt

~/.config/shell_gpt/.sgptrc    - Runtime configuration
~/.config/shell_gpt/functions/   - Custom and built-in functions
~/.config/shell_gpt/roles/       - Default and custom roles
/tmp/shell_gpt/chat_cache/       - Chat session storage (configurable)
/tmp/shell_gpt/cache/            - Request cache (configurable)