👀 ShellGPT on Debian: Clean Installation with pipx

Date Created: 2025-05-18
By: 16BitMiker
[ BACK.. ]

Tired of switching between your terminal and browser to ask ChatGPT questions? ShellGPT brings the power of OpenAI’s language models directly to your command line. In this guide, we’ll walk through setting up ShellGPT on Debian using pipx — a clean, reliable way to install Python tools in isolated environments that don’t interfere with your system-wide packages.

Let’s make this smooth and bulletproof, including a key update about the python3-venv requirement. 🛠️

📋 What is ShellGPT?

ShellGPT (invoked via the sgpt command) is a terminal-based interface that connects to OpenAI’s GPT models. It allows you to:

🧠 Ask questions and get answers without leaving your terminal
📜 Generate shell commands from natural language descriptions
🧑‍💻 Get code snippets, explanations, and programming help
🗨️ Maintain persistent chat sessions for ongoing tasks

If you’ve ever wished your shell had a built-in AI assistant, ShellGPT is for you.

🚀 Installation with pipx

Installing via pipx keeps things clean by creating dedicated virtual environments for Python tools. This avoids polluting your system Python installation and makes upgrades and removals safe.

▶️ Step 1: Install pipx and python3-venv

On Debian systems, pipx is available via APT, but it requires the python3-venv package to function correctly. Without it, pipx cannot create the virtual environments it relies on.

Install both like this:


sudo apt update
sudo apt install pipx python3-venv -y

📦 Why include python3-venv explicitly?
While pipx may pull it in as a dependency in some cases, this isn’t guaranteed across all Debian versions. Explicitly installing python3-venv ensures pipx has the tools it needs to work correctly.

Now, make sure pipx is in your shell’s PATH:


xxxxxxxxxx
pipx ensurepath

Then reload your shell configuration:


xxxxxxxxxx
source ~/.bashrc

⏎ Or restart your terminal to apply changes.

▶️ Step 2: Install ShellGPT Using pipx

With pipx ready, installing ShellGPT is easy:


xxxxxxxxxx
pipx install shell-gpt

This installs ShellGPT into its own virtual environment and adds the sgpt command to your PATH. You can now run it from anywhere without affecting your system Python installation.

▶️ Step 3: Set Your OpenAI API Key

Try running ShellGPT to initialize configuration:


xxxxxxxxxx
sgpt "Hello, world!"

If it’s your first run, ShellGPT will prompt you for your OpenAI API key.

🔑 You can get your key from:
https://platform.openai.com/account/api-keys

Once entered, your key is stored securely in:


xxxxxxxxxx
~/.config/shell_gpt/.sgptrc

You won’t need to enter it again unless you reset the config.

📋 Basic Usage Examples

Here’s how to get started with common use cases:

📋 Ask Factual Questions


xxxxxxxxxx
sgpt "What's the capital of Japan?"

Expected response:
🇯🇵 Tokyo

📋 Generate Shell Commands


xxxxxxxxxx
sgpt --shell "Find all PNG files modified in the last 7 days"

Example output:


xxxxxxxxxx
find . -type f -name "*.png" -mtime -7

✅ You can copy and paste the result or use ShellGPT’s integration to run commands directly (with caution).

📋 Generate Code Snippets


xxxxxxxxxx
sgpt --code "Write a Python function to check if a string is a palindrome"

Example output:


xxxxxxxxxx
def is_palindrome(s):
    return s == s[::-1]

📋 Use Persistent Chat Sessions

ShellGPT supports named chat sessions for ongoing conversations:


xxxxxxxxxx
sgpt --chat devhelp "How do I handle errors in Bash scripts?"
# Continue the conversation
sgpt --chat devhelp "Can you show me an example?"

This is great for debugging, coding assistance, or brainstorming ideas across multiple prompts.

🔧 Configuration Options

ShellGPT stores settings in:


xxxxxxxxxx
~/.config/shell_gpt/.sgptrc

You can edit this file manually or allow ShellGPT to update it interactively.

▶️ Common Configuration Fields


xxxxxxxxxx
OPENAI_API_KEY = sk-xxxxxxxxxxxxxxxxxxxx
DEFAULT_MODEL = gpt-4o
TEMPERATURE = 0.7
CACHE_ENABLE = true
REQUEST_TIMEOUT = 60

🔁 DEFAULT_MODEL: Supported models include gpt-4o, gpt-4, gpt-3.5-turbo, etc.
🔥 TEMPERATURE: Controls creativity. Use 0.2–0.5 for factual responses, and 0.7+ for creative writing.
💾 CACHE_ENABLE: Avoids repeated API calls for identical prompts.
⏱️ REQUEST_TIMEOUT: Total time (in seconds) before ShellGPT gives up on waiting for a response.

🔄 Keeping ShellGPT Updated

To upgrade to the latest version:


xxxxxxxxxx
pipx upgrade shell-gpt

Check for outdated packages:


xxxxxxxxxx
pipx list --outdated

You’ll see version comparisons and upgrade prompts.

🔎 Troubleshooting Common Issues

▶️ Command Not Found: sgpt

If sgpt isn’t found after install:


xxxxxxxxxx
pipx ensurepath
source ~/.bashrc

Still not working? Check that ~/.local/bin is in your PATH.

▶️ Missing python3-venv

Symptoms:

pipx install fails with "No module named venv"
sgpt doesn't install properly

Fix:


xxxxxxxxxx
sudo apt install python3-venv

Then reinstall ShellGPT:


xxxxxxxxxx
pipx reinstall shell-gpt

▶️ API Key Issues

If you get 401 errors or see messages about authentication:

Make sure your key is correct in ~/.config/shell_gpt/.sgptrc
Check your OpenAI usage limits
Try resetting your config:


xxxxxxxxxx
rm ~/.config/shell_gpt/.sgptrc

Then run sgpt again to reconfigure.

🏁 Conclusion

Installing ShellGPT with pipx on Debian is a clean and maintainable way to bring AI into your terminal workflow. With the right setup:

You avoid polluting your system Python environment
You get a globally available sgpt command
You can easily manage updates and configs
You gain instant access to OpenAI models without leaving your shell

Whether you're scripting, researching, or just exploring ideas, ShellGPT can dramatically enhance your productivity in the terminal.

Happy prompting! 🧠💻