# GDELT CLI

**The command-line interface for the GDELT Project — built for agents, optimized for automation.**

[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/dipankar/gdelt-cli/ci.yml?branch=main)](https://github.com/dipankar/gdelt-cli/actions)
[![Release](https://img.shields.io/github/v/release/dipankar/gdelt-cli)](https://github.com/dipankar/gdelt-cli/releases)

---

## What is GDELT?

The [GDELT Project](https://www.gdeltproject.org/) monitors news media from nearly every country in 100+ languages, updating every 15 minutes. It's the largest open dataset of global human society, tracking events, sentiment, themes, and entities across the world's news.

## Why GDELT CLI?

Traditional GDELT access requires complex API calls and manual data wrangling. **GDELT CLI** provides:

- **Agent-First Design** — Structured JSON output, machine-readable help, predictable exit codes
- **Local Analytics** — DuckDB-powered queries on downloaded data, no API limits
- **Smart Caching** — SQLite cache reduces redundant API calls
- **MCP Server** — Expose GDELT as tools for AI assistants (Claude, etc.)
- **Zero Config** — Sensible defaults, works out of the box

---

## Quick Start

### Installation

```bash
# One-line install (downloads binary or builds from source)
curl -fsSL https://raw.githubusercontent.com/dipankar/gdelt-cli/main/install.sh | bash

# Or with Cargo
cargo install --git https://github.com/dipankar/gdelt-cli

# Or build locally
git clone https://github.com/dipankar/gdelt-cli
cd gdelt-cli
cargo build --release
```

### First Commands

```bash
# Search recent news
gdelt doc search "climate change" --max-records 10

# Get geographic data for events
gdelt geo search "protests" --timespan 7d

# Download and sync local data
gdelt data sync --days 7

# Query local events database
gdelt events query --country US --start 2024-01-01

# Get machine-readable help
gdelt --help-json
```

---

## Agent & Automation Features

GDELT CLI is designed for programmatic use by AI agents, scripts, and automation pipelines.

### Structured Output

All commands support multiple output formats:

```bash
gdelt doc search "elections" -o json    # JSON (default for pipes)
gdelt doc search "elections" -o jsonl   # JSON Lines (streaming)
gdelt doc search "elections" -o csv     # CSV
gdelt doc search "elections" -o table   # Human-readable table
```

### Machine-Readable Help

```bash
# Get complete command schema as JSON
gdelt --help-json

# Get schema for a specific command
gdelt schema command doc.search

# List all available tools (MCP-compatible)
gdelt schema tools
```

### Predictable Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Validation error |
| 3 | Network error |
| 4 | API error |
| 5 | Rate limited |
| 10 | Database error |
| 11 | Cache error |
| 20 | Not found |

### Environment Variables

```bash
GDELT_OUTPUT=json          # Default output format
GDELT_QUIET=1              # Suppress non-essential output
GDELT_NO_CACHE=1           # Bypass cache
GDELT_TIMEOUT=60           # Request timeout in seconds
```

---

## Command Reference

### DOC API — News Article Search

```bash
# Full-text search
gdelt doc search "artificial intelligence"

# With filters
gdelt doc search "AI" \
  --timespan 7d \
  --country US \
  --lang english \
  --tone-min -5 --tone-max 5 \
  --max-records 100

# Timeline analysis
gdelt doc timeline "bitcoin" --mode tone --timespan 30d

# Word cloud data
gdelt doc wordcloud "cryptocurrency" --timespan 24h
```

### GEO API — Geographic Search

```bash
# Point data for mapping
gdelt geo search "earthquake" --format point

# Heatmap data
gdelt geo search "protests" --format heatmap --timespan 7d
```

### TV API — Television News

```bash
# Search TV clips
gdelt tv search "president" --timespan 24h

# Station coverage
gdelt tv stations --country US
```

### Local Data & Analytics

```bash
# Download historical data
gdelt data download --start 2024-01-01 --end 2024-01-31 --type events

# Sync latest updates
gdelt data sync

# Query local events
gdelt events query \
  --actor USA \
  --event-code 14* \
  --goldstein-min -10 \
  --limit 100

# Query GKG (Global Knowledge Graph)
gdelt gkg query --theme POLITICS --person "Biden"

# Trend analysis
gdelt analytics trends "Ukraine" --granularity day --days 90

# Entity extraction
gdelt analytics entities --type person --min-count 10

# Sentiment analysis
gdelt analytics sentiment "elections" --by region
```

### Database Management

```bash
# View statistics
gdelt db stats

# Export data
gdelt db export events --format parquet --output events.parquet

# Run custom SQL
gdelt db query "SELECT COUNT(*) FROM events WHERE quad_class = 4"

# Optimize database
gdelt db vacuum
```

---

## MCP Server (AI Assistant Integration)

GDELT CLI can run as an MCP (Model Context Protocol) server, exposing GDELT data as tools for AI assistants.

```bash
# Start MCP server (stdio transport)
gdelt serve

# With configuration
gdelt serve --port 8080
```

### Available Tools

When running as an MCP server, the following tools are exposed:

- `gdelt_search` — Search news articles
- `gdelt_timeline` — Get volume/tone over time
- `gdelt_geo` — Geographic event data
- `gdelt_events_query` — Query local events database
- `gdelt_gkg_query` — Query Global Knowledge Graph
- `gdelt_analytics` — Run trend/sentiment analysis

### Claude Desktop Integration

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gdelt": {
      "command": "gdelt",
      "args": ["serve"]
    }
  }
}
```

---

## Background Daemon

Run GDELT sync as a background service:

```bash
# Start daemon
gdelt daemon start --sync --mcp

# Check status
gdelt daemon status

# View logs
gdelt daemon logs --tail 100

# Stop daemon
gdelt daemon stop

# Install as system service
gdelt daemon install --systemd  # Linux
gdelt daemon install --launchd  # macOS
```

---

## Configuration

Configuration file: `~/.config/gdelt/config.toml`

```toml
[general]
default_format = "json"
timezone = "UTC"

[network]
timeout_secs = 30
retries = 3
rate_limit_rps = 5.0

[cache]
enabled = true
max_size_mb = 500

[cache.ttl]
doc_search = "1h"
geo = "24h"

[database]
memory_limit = "2GB"

[defaults.doc]
timespan = "24h"
max_records = 75
sort = "hybrid-rel"
```

---

## Data Storage

| Directory | Contents |
|-----------|----------|
| `~/.local/share/gdelt/` | DuckDB database, downloaded files |
| `~/.cache/gdelt/` | API response cache (SQLite) |
| `~/.config/gdelt/` | Configuration files |

---

## Development

### Building from Source

```bash
# Clone repository
git clone https://github.com/dipankar/gdelt-cli
cd gdelt-cli

# Build debug
cargo build

# Build release
cargo build --release

# Run tests
cargo test

# Build with MCP support
cargo build --release --features mcp
```

### Project Structure

```
src/
├── api/          # GDELT API clients (DOC, GEO, TV)
├── analytics/    # Trend, sentiment, entity analysis
├── cli/          # Command definitions and handlers
├── config/       # Configuration schema
├── daemon/       # Background sync service
├── data/         # Download and import logic
├── db/           # DuckDB and SQLite interfaces
├── mcp/          # MCP server implementation
├── models/       # Data models and CAMEO codes
└── error/        # Error types and exit codes
```

### Running Tests

```bash
# All tests
cargo test

# With output
cargo test -- --nocapture

# Specific test
cargo test test_validate_date
```

---

## CAMEO Event Codes

GDELT uses CAMEO (Conflict and Mediation Event Observations) codes. Quick reference:

| Code | Category | Goldstein |
|------|----------|-----------|
| 01 | Make public statement | 0.0 |
| 02 | Appeal | 3.0 |
| 03 | Express intent to cooperate | 4.0 |
| 04 | Consult | 1.0 |
| 05 | Diplomatic cooperation | 3.5 |
| 06 | Material cooperation | 6.0 |
| 07 | Provide aid | 7.0 |
| 08 | Yield | 5.0 |
| 09 | Investigate | -0.5 |
| 10 | Demand | -5.0 |
| 11 | Disapprove | -2.0 |
| 12 | Reject | -4.0 |
| 13 | Threaten | -7.0 |
| 14 | Protest | -6.5 |
| 15 | Exhibit force posture | -7.5 |
| 16 | Reduce relations | -6.0 |
| 17 | Coerce | -7.0 |
| 18 | Assault | -9.0 |
| 19 | Fight | -10.0 |
| 20 | Mass violence | -10.0 |

```bash
# List all codes
gdelt events codes list

# Search codes
gdelt events codes search "protest"

# Describe a code
gdelt events codes describe 14
```

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Links

- [GDELT Project](https://www.gdeltproject.org/)
- [GDELT Documentation](https://blog.gdeltproject.org/gdelt-2-0-our-global-world-in-realtime/)
- [CAMEO Event Codes](https://parusanalytics.com/eventdata/data.dir/cameo.html)
- [Issues & Feature Requests](https://github.com/dipankar/gdelt-cli/issues)
