zapgpt

A minimalist CLI tool to chat with LLMs from your terminal. Supports multiple providers including OpenAI, OpenRouter, Together, Replicate, DeepInfra, and GitHub AI. For local provider like Ollama, you can use provider local and for omniroute, you can use omniroute as provider.

███████╗ █████╗ ██████╗  ██████╗ ██████╗ ████████╗
╚══███╔╝██╔══██╗██╔══██╗██╔════╝ ██╔══██╗╚══██╔══╝
  ███╔╝ ███████║██████╔╝██║  ███╗██████╔╝   ██║
 ███╔╝  ██╔══██║██╔═══╝ ██║   ██║██╔═══╝    ██║
███████╗██║  ██║██║     ╚██████╔╝██║        ██║
╚══════╝╚═╝  ╚═╝╚═╝      ╚═════╝ ╚═╝        ╚═╝
         GPT on the CLI. Like a boss.

zapgpt is a CLI and Python API for querying multiple LLM providers. It supports reusable system prompts, text and image attachments, local usage tracking, quiet output for automation, and provider-specific configuration.

Current package version: v3.6.

Introduction video

💾 Requirements

• Python 3.9+
• uv (recommended - blazingly fast Python package manager)
• pip (alternative to uv)

🚀 Installation

Option 1: Install with uv (⚡ Recommended)

uv tool install zapgpt

Why uv? uv is blazingly fast and handles CLI tools perfectly. It installs zapgpt globally and manages dependencies automatically.

Don't have uv? Install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Option 2: Install from PyPI

uv tool install zapgpt

Option 3: Development Installation

With uv (recommended):

git clone https://github.com/raj77in/zapgpt.git
cd zapgpt
uv sync
uv run zapgpt "test"

# Optional: Set up pre-commit hooks for code quality
./setup-pre-commit.sh

With pip:

git clone https://github.com/raj77in/zapgpt.git
cd zapgpt
pip install -e .

Option 4: From Source (Classic method)

git clone https://github.com/raj77in/zapgpt.git
cd zapgpt
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

🔑 Environment Variables

ZapGPT only requires the API key for the provider you're using. Set the appropriate environment variable:

Example:

# For OpenAI (default provider)
export OPENAI_API_KEY="your-openai-api-key-here"

# For OpenRouter
export OPENROUTER_KEY="your-openrouter-key-here"

🧠 Usage

After installation, you can use zapgpt directly from the command line:

# Basic usage (uses OpenAI by default)
zapgpt "What's the meaning of life?"

# Use different providers
zapgpt --provider openrouter "Explain quantum computing"
zapgpt --provider together "Write a Python function"
zapgpt --provider github "Debug this code"

# Use specific models
zapgpt -m gpt-4o "Complex reasoning task"
zapgpt --provider openrouter -m anthropic/claude-3.5-sonnet "Creative writing"

Interactive Mode

zapgpt  # Starts interactive mode

Development Usage

With uv:

uv run zapgpt "Your question here"

With Python:

python -m zapgpt "Your question here"
# or
python zapgpt/main.py "Your question here"

Quiet Mode (for Scripting)

# Suppress all output except the LLM response
zapgpt --quiet "What is the capital of France?"

# Perfect for shell scripts
RESPONSE=$(zapgpt -q "Summarize this in one word: Machine Learning")
echo "Result: $RESPONSE"

File Input (for Automation)

# Send file contents to LLM
zapgpt --file /path/to/file.txt "Analyze this log file"

# Compare exactly two files. Each filename is included in the prompt.
zapgpt --files before.py after.py "Explain the changes"

# Analyze command output
nmap -sV target.com > scan_results.txt
zapgpt -f scan_results.txt --use-prompt vuln_assessment "Analyze these scan results"

# Process multiple files
for file in *.log; do
    zapgpt -q -f "$file" "Summarize security events" >> summary.txt
done

Image Input

Use --image once or repeat it to send multiple images to a vision-capable model:

zapgpt --image screenshot.png "Describe this screenshot"
zapgpt -m gpt-4o \
  --image front.jpg \
  --image back.jpg \
  "Compare these images"

The image is embedded as a base64 data URL. Supported file types are determined from the filename extension and the selected provider/model must support image input.

Combining Prompts

Repeat --use-prompt to concatenate prompt templates. By default, common_base is prepended; use --no-default to omit it.

zapgpt \
  --use-prompt coding \
  --use-prompt vuln_assessment \
  "Review this code"

zapgpt --no-default --use-prompt coding "Review this function"

Automation Examples

# Penetration Testing Agent
#!/bin/bash
TARGET="example.com"

# 1. Reconnaissance
nmap -sV $TARGET > nmap_results.txt
RESPONSE=$(zapgpt -q -f nmap_results.txt --use-prompt vuln_assessment "Identify potential vulnerabilities")
echo "Vulnerabilities found: $RESPONSE"

# 2. Web Analysis
nikto -h $TARGET > nikto_results.txt
zapgpt -f nikto_results.txt "Prioritize these web vulnerabilities" > web_analysis.txt

# 3. Generate Report
zapgpt -q "Create executive summary" -f web_analysis.txt > final_report.md

# Log Analysis Agent
#!/bin/bash
# Monitor and analyze system logs
tail -n 100 /var/log/auth.log > recent_auth.log
ALERT=$(zapgpt -q -f recent_auth.log "Detect suspicious login attempts")

if [[ $ALERT == *"suspicious"* ]]; then
    echo "Security Alert: $ALERT" | mail -s "Security Alert" admin@company.com
fi

# Code Review Agent
#!/bin/bash
# Automated code review
for file in src/*.py; do
    REVIEW=$(zapgpt -q -f "$file" --use-prompt coding "Review this code for security issues")
    echo "File: $file" >> code_review.md
    echo "Review: $REVIEW" >> code_review.md
    echo "---" >> code_review.md
done

🐍 Programmatic API

ZapGPT can be imported and used in your Python scripts:

Basic Usage

from zapgpt import query_llm

# Simple query
response = query_llm("What is Python?", provider="openai")
print(response)

# With different provider
response = query_llm(
    "Explain quantum computing",
    provider="openrouter",
    model="anthropic/claude-3.5-sonnet"
)

Advanced Usage

from zapgpt import query_llm

# Use predefined prompts
code_review = query_llm(
    "Review this Python function: def hello(): print('hi')",
    provider="openai",
    use_prompt="coding",
    model="gpt-4o"
)

# Custom system prompt
response = query_llm(
    "Write a haiku about programming",
    provider="openai",
    system_prompt="You are a poetic programming mentor.",
    temperature=0.8
)

# Combine prompts without prepending common_base
response = query_llm(
    "Review this function",
    use_prompt=["coding", "vuln_assessment"],
    no_default=True,
)

# Send one or more images
response = query_llm(
    "Compare these diagrams",
    model="gpt-4o",
    images=["architecture-v1.png", "architecture-v2.png"],
)

# Error handling
try:
    response = query_llm("Hello", provider="openai")
except EnvironmentError as e:
    print(f"Missing API key: {e}")
except ValueError as e:
    print(f"Invalid provider: {e}")

API Parameters

Environment Variables

Set the appropriate API key for your chosen provider:

import os
os.environ['OPENAI_API_KEY'] = 'your-key-here'

from zapgpt import query_llm
response = query_llm("Hello world", provider="openai")

Python Automation Examples

# Penetration Testing Automation
import subprocess
from zapgpt import query_llm

def analyze_nmap_scan(target):
    # Run nmap scan
    result = subprocess.run(['nmap', '-sV', target], capture_output=True, text=True)

    # Analyze with LLM
    analysis = query_llm(
        f"Analyze this nmap scan: {result.stdout}",
        provider="openai",
        use_prompt="vuln_assessment"
    )
    return analysis

vulns = analyze_nmap_scan("example.com")
print(f"Vulnerabilities: {vulns}")

# Log Analysis Agent
from zapgpt import query_llm

def monitor_logs(log_file):
    with open(log_file, 'r') as f:
        logs = f.read()

    alert = query_llm(
        f"Detect suspicious activity: {logs}",
        provider="openai",
        quiet=True
    )

    if "suspicious" in alert.lower():
        print(f"ALERT: {alert}")
        return True
    return False

# Monitor auth logs
monitor_logs('/var/log/auth.log')

Usage Video

🛠️ Features

• OpenAI, OpenRouter, Together, Replicate, DeepInfra, GitHub AI, and local providers
• Repeatable prompt templates with optional common_base
• Single-file and two-file text attachments
• Single and multiple image attachments for vision-capable models
• Quiet output for shell automation
• Local usage and estimated cost tracking
• Custom prompts and provider defaults in ~/.config/zapgpt/

📝 Configuration & Prompts

ZapGPT stores its configuration and prompts in ~/.config/zapgpt/:

• Configuration directory: ~/.config/zapgpt/
• Prompts directory: ~/.config/zapgpt/prompts/
• Database file: ~/.config/zapgpt/gpt_usage.db

Managing Prompts

On first run, zapgpt automatically copies default prompts to your config directory. You can:

• View config location: zapgpt --config
• List available prompts: zapgpt --list-prompt
• Use a specific prompt: zapgpt --use-prompt coding "Your question"
• Add custom prompts: Create .json files in ~/.config/zapgpt/prompts/
• Modify existing prompts: Edit the .json files in your prompts directory

Default Prompts Included

• coding - Programming and development assistance
• cyber_awareness - Cybersecurity guidance
• vuln_assessment - Vulnerability assessment help
• kalihacking - Kali Linux and penetration testing
• prompting - Prompt engineering assistance
• powershell - PowerShell scripting help
• default - General purpose prompt
• common_base - Base prompt added to all others

Running Tests

The test suite uses mocked provider clients and does not require network access or valid API keys.

# Local environment
python -m pip install -e ".[test]"
python -m pytest tests -q

# uv
uv sync --all-extras --dev
uv run pytest tests -q

# Auto-detect Podman or Docker
./run_tests_in_docker.sh

# Select an engine explicitly
CONTAINER_ENGINE=docker ./run_tests_in_docker.sh
CONTAINER_ENGINE=podman ./run_tests_in_docker.sh

GitHub Actions runs the test matrix on Python 3.9 through 3.13 and also builds and executes Dockerfile.test.

🧪 Example

$ zapgpt "Summarize the Unix philosophy."
> Small is beautiful. Do one thing well. Write programs that work together.

🙌 Credits

Built with ❤️ by Amit Agarwal aka — because LLMs deserve a good CLI.

🧙‍♂️ License

MIT — do whatever, just don't blame me if it becomes sentient.