# GDELT CLI
**The command-line interface for the GDELT Project — built for agents, optimized for automation.**
[](https://www.rust-lang.org/)
[](LICENSE)
[](https://github.com/dipankar/gdelt-cli/actions)
[](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)
# 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
| 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
| `~/.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:
| 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)