Metadata-Version: 2.4
Name: zapgpt
Version: 3.6.2
Summary: A command-line tool for interacting with various LLM providers
Author-email: Amit Agarwal <amit@labnol.org>
Maintainer-email: Amit Agarwal <amit@example.com>
License: MIT License
        
        Copyright (c) 2025 Amit Agarwal
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/raj77in/zapgpt
Project-URL: Repository, https://github.com/raj77in/zapgpt
Project-URL: Issues, https://github.com/raj77in/zapgpt/issues
Project-URL: Documentation, https://github.com/raj77in/zapgpt#readme
Keywords: ai,llm,gpt,openai,anthropic,mistral,cli,chat,terminal
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.54.0
Requires-Dist: requests>=2.32.3
Requires-Dist: tabulate>=0.9.0
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: rich>=13.9.4
Requires-Dist: pygments>=2.18.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: rich-argparse>=1.7.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typing-extensions>=4.12.2
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: importlib-resources>=6.4.0; python_version < "3.9"
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-mock>=3.10; extra == "test"
Dynamic: license-file

# zapgpt

![Intro image](intro.png)

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

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

[![Introduction](https://i.ytimg.com/vi/hpiVtj_gSD4/hqdefault.jpg)](https://www.youtube.com/watch?v=hpiVtj_gSD4)

## 💾 Requirements

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

## 🚀 Installation

### Option 1: Install with `uv` (⚡ Recommended)

```bash
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:

```bash
# 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

```bash
uv tool install zapgpt
```

### Option 3: Development Installation

**With uv (recommended):**

```bash
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:**

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

### Option 4: From Source (Classic method)

```bash
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](https://platform.openai.com/account/api-keys) |
| OpenRouter | `OPENROUTER_KEY` | [openrouter.ai](https://openrouter.ai/keys) |
| Together | `TOGETHER_API_KEY` | [api.together.xyz](https://api.together.xyz/settings/api-keys) |
| Replicate | `REPLICATE_API_TOKEN` | [replicate.com](https://replicate.com/account/api-tokens) |
| DeepInfra | `DEEPINFRA_API_TOKEN` | [deepinfra.com](https://deepinfra.com/dash/api_keys) |
| GitHub | `GITHUB_KEY` | [github.com](https://github.com/settings/tokens) |

**Example:**

```bash
# 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:

```bash
# 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

```bash
zapgpt  # Starts interactive mode
```

### Development Usage

**With uv:**

```bash
uv run zapgpt "Your question here"
```

**With Python:**

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

### Quiet Mode (for Scripting)

```bash
# 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)

```bash
# 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:

```bash
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.

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

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

### Automation Examples

```bash
# 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
```

```bash
# 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
```

```bash
# 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

```python
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

```python
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:

```python
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

```python
# 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}")
```

```python
# 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

[![Using zapgpt for pentesting on Kali](https://i.ytimg.com/vi/vDTwIsEUheE/hqdefault.jpg)](https://www.youtube.com/watch?v=hpiVtj_gSD4)

## 🛠️ 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.

```bash
# 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

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

## 🙌 Credits

Built with ❤️ by [Amit Agarwal aka](https://github.com/raj77in) — because LLMs deserve a good CLI.

## 🧙‍♂️ License

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