nGPT

<p align="center"> <img src="https://raw.githubusercontent.com/nazdridoy/ngpt/main/.github/banner.svg" alt="nGPT Banner"> </p> <p align="center"> <a href="https://pypi.org/project/ngpt/"><img src="https://img.shields.io/pypi/v/ngpt.svg" alt="PyPI version"></a> <a href="https://aur.archlinux.org/packages/ngpt"><img alt="AUR Version" src="https://img.shields.io/aur/version/ngpt"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://nazdridoy.github.io/ngpt/"><img src="https://img.shields.io/badge/docs-available-brightgreen.svg" alt="Documentation"></a> <a href="https://deepwiki.com/nazdridoy/ngpt"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki [DOCS]"></a> </p> <p align="center"> <a href="https://nazdridoy.github.io/ngpt/installation/#linuxmacos"><img src="https://img.shields.io/badge/Linux-support-blue?logo=linux" alt="Linux"></a> <a href="https://nazdridoy.github.io/ngpt/installation/#windows"><img src="https://img.shields.io/badge/Windows-support-blue?logo=windows" alt="Windows"></a> <a href="https://nazdridoy.github.io/ngpt/installation/#linuxmacos"><img src="https://img.shields.io/badge/macOS-support-blue?logo=apple" alt="macOS"></a> <a href="https://nazdridoy.github.io/ngpt/installation/#android-termux"><img src="https://img.shields.io/badge/Android-Termux-blue?logo=android" alt="Android"></a> </p>

🤖 nGPT - A lightning-fast CLI tool that brings any OpenAI-compatible LLM (OpenAI, Ollama, Groq, Claude, Gemini) directly to your terminal. Generate code, craft git commits, execute shell commands, rewrite text, and chat interactively, all with seamless provider switching and real-time streaming.

Features

• ✅ Versatile: Powerful and easy-to-use CLI tool for various AI tasks
• 🪶 Lightweight: Minimal dependencies with everything you need included
• 🔄 API Flexibility: Works with OpenAI, Ollama, Groq, Claude, Gemini, and any OpenAI-compatible endpoint
• 💬 Interactive Chat: Continuous conversation with memory in modern UI
• 📊 Streaming Responses: Real-time output for better user experience
• 🔍 Web Search: Enhance any model with contextual information from the web, using advanced content extraction to identify the most relevant information from web pages
• 📥 Stdin Processing: Process piped content by using {} placeholder in prompts
• 🎨 Markdown Rendering: Beautiful formatting of markdown and code with syntax highlighting
• ⚡ Real-time Markdown: Stream responses with live updating syntax highlighting and formatting
• ⚙️ Multiple Configurations: Cross-platform config system supporting different profiles
• 💻 Shell Command Generation: OS-aware command execution
• 🧠 Text Rewriting: Improve text quality while maintaining original tone and meaning
• 🧩 Clean Code Generation: Output code without markdown or explanations
• 📝 Rich Multiline Editor: Interactive multiline text input with syntax highlighting and intuitive controls
• 📑 Git Commit Messages: AI-powered generation of conventional, detailed commit messages from git diffs
• 🎭 System Prompts: Customize model behavior with custom system prompts
• 🤖 Custom Roles: Create and use reusable AI roles for specialized tasks
• 📃 Conversation Logging: Save your conversations to text files for later reference
• 💾 Session Management: Save, load, and list interactive chat sessions with advanced session manager
• 🔌 Modular Architecture: Well-structured codebase with clean separation of concerns
• 🔄 Provider Switching: Easily switch between different LLM providers with a single parameter
• 🚀 Performance Optimized: Fast response times and minimal resource usage

See the Feature Overview for more details.

Table of Contents

• Features
• Installation
• Quick Start
• Usage
  • Command Line Options
  • Documentation
• Documentation
• Configuration
  • API Key Setup
  • OpenAI API Key
  • Google Gemini API Key
  • CLI Configuration
  • Interactive Configuration
  • Configuration File
  • Configuration Priority
• Contributing
• License

Installation

# Installation with pip
pip install ngpt

# Or install with uv (faster installation)
uv pip install ngpt

# Or install globally as a CLI tool (recommended for command-line usage)
uv tool install ngpt

# Arch Linux: install from AUR
paru -S ngpt

Requires Python 3.8 or newer.

For detailed installation instructions, see the Installation Guide.

Quick Start

# Chat with default settings
ngpt "Tell me about quantum computing"

# Alternatively, run as a Python module
python -m ngpt "Tell me about quantum computing"

# Start an interactive chat session with conversation memory
ngpt -i
# Inside interactive mode, you can use commands like:

# /editor   - Open multiline editor for complex inputs
# /exit     - Exit the session (also 'exit', 'quit', 'bye' without '/')
# /help     - Show help menu
# /reset    - Reset the conversation
# /sessions - Manage saved sessions
# /transcript - Show recent conversation exchanges

# Keyboard shortcuts:
# Ctrl+E    - Open multiline editor for complex inputs
# Ctrl+C    - Exit the session
# ↑/↓       - Navigate command history

# Session management improvements:
# - Commands like preview, load, rename, delete now default to the latest session
# - Example: 'load' (loads the latest session) vs 'load 2' (loads session at index 2)

# Return response without streaming
ngpt --plaintext "Tell me about quantum computing"

# Generate code
ngpt --code "function to calculate the Fibonacci sequence"

# Generate code with real-time syntax highlighting (default)
ngpt --code "function to calculate the Fibonacci sequence"

# Generate code without streaming or markdown rendering
ngpt --code --plaintext "function to calculate the Fibonacci sequence"

# Generate and execute shell commands
ngpt --shell "list all files in the current directory"

# Read from stdin and use the content in your prompt
echo "What is this text about?" | ngpt --pipe "Analyze the following text: {}"

# Use interactive multiline editor to enter a command description (when no argument is provided)
ngpt -s

# Use interactive multiline editor to enter code description (when no argument is provided)
ngpt -c

# Pipe a command description to shell mode
echo "list all files" | ngpt -s

# Pipe a code description to code mode
echo "create a python request" | ngpt -c --language python

# Using here-string (<<<) for quick single-line input 
ngpt --pipe {} <<< "What is the best way to learn shell redirects?"

# Using standard input redirection to process file contents
ngpt --pipe "summarise {}" < README.md

# Using here-document (<<EOF) for multiline input
ngpt --pipe {} << EOF                                              
What is the best way to learn Golang?
Provide simple hello world example.
EOF

# Create a custom role for specialized tasks
ngpt --role-config create json_generator

# Use a custom role for specific tasks
ngpt --role json_generator "Generate user data with name, email, and address" 

# Use a role from the Role Gallery (first create it, then use it)
ngpt --role-config create sql_expert
# Paste the SQL Expert role from https://nazdridoy.github.io/ngpt/examples/role-gallery/
ngpt --role sql_expert "Write a query to find all users who made a purchase in the last 30 days"

# Rewrite text to improve quality while preserving tone and meaning
echo "your text" | ngpt -r

# Rewrite text from a command-line argument
ngpt -r "your text to rewrite"

# Use interactive multiline editor if no argument is provided
ngpt -r

# Rewrite text from a file
cat file.txt | ngpt -r

# Generate AI-powered git commit messages for staged changes
ngpt -g

# Generate commit message from staged changes with a context directive
ngpt -g --preprompt "type:feat"

# Process large diffs in chunks with recursive analysis
ngpt -g --rec-chunk

# Process a diff file instead of staged changes
ngpt -g --diff /path/to/changes.diff

# Use piped diff content for commit message generation
git diff HEAD~1 | ngpt -g --pipe

# Generate a commit message with logging for debugging
ngpt -g --log commit_log.txt

# Use interactive multiline editor to enter text to rewrite
ngpt -r

# Display markdown responses with real-time formatting (default)
ngpt "Explain markdown syntax with examples"

# Display responses without markdown rendering
ngpt --plaintext "Explain markdown syntax with examples"

# Use multiline editor for complex prompts
ngpt --text

# Use custom system prompt
ngpt --preprompt "You are a Linux expert" "How do I find large files?"

# Log your conversation to a file
ngpt --interactive --log conversation.log

# Create a temporary log file automatically
ngpt --log "Tell me about quantum computing"

# Process text from stdin using the {} placeholder
cat README.md | ngpt --pipe "Summarize this document: {}"

# Use different model providers by specifying the provider name
ngpt --provider Groq "Explain quantum computing"

# Compare outputs from different providers
ngpt --provider OpenAI --plaintext "Explain quantum physics" > openai_response.txt
ngpt --provider Ollama --plaintext "Explain quantum physics" > ollama_response.txt

# Show all API configurations
ngpt --show-config --all

# List available models for the active configuration
ngpt --list-models

# List models for a specific configu