zapgpt 3.6.3

A command-line tool for interacting with various LLM providers

zapgpt

A minimalist CLI tool to chat with LLMs from your terminal. Supports multiple providers including OpenAI, OpenRouter, Together, Replicate, DeepInfra, and GitHub AI.

███████╗ █████╗ ██████╗  ██████╗ ██████╗ ████████╗
╚══███╔╝██╔══██╗██╔══██╗██╔════╝ ██╔══██╗╚══██╔══╝
  ███╔╝ ███████║██████╔╝██║  ███╗██████╔╝   ██║
 ███╔╝  ██╔══██║██╔═══╝ ██║   ██║██╔═══╝    ██║
███████╗██║  ██║██║     ╚██████╔╝██║        ██║
╚══════╝╚═╝  ╚═╝╚═╝      ╚═════╝ ╚═╝        ╚═╝
         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:

Provider	Environment Variable	Get API Key
OpenAI	OPENAI_API_KEY	platform.openai.com
OpenRouter	OPENROUTER_KEY	openrouter.ai
Together	TOGETHER_API_KEY	api.together.xyz
Replicate	REPLICATE_API_TOKEN	replicate.com
DeepInfra	DEEPINFRA_API_TOKEN	deepinfra.com
GitHub	GITHUB_KEY	github.com

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" [e-mail]
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

Parameter	Type	Default	Description
prompt	str	Required	Your question/prompt
provider	str	"openai"	LLM provider to use
model	str	None	Specific model (overrides prompt default)
system_prompt	str	None	Custom system prompt
use_prompt	str or list[str]	None	Use one or more predefined prompt templates
image	str	None	Path to one image
images	list[str]	None	Paths to multiple images
temperature	float	0.3	Response randomness (0.0-1.0)
max_tokens	int	None	Maximum response length
quiet	bool	True	Suppress logging output
no_default	bool	False	Do not prepend the common_base prompt

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.