Skip to content

neul-labs/gdelt-cli

BranchesTags

Repository files navigation

GDELT CLI

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

Rust License: MIT Build Status Release

What is GDELT?

The GDELT Project 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

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

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

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

First Commands

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

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

# 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

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

# 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

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

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

TV API — Television News

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

# Station coverage
gdelt tv stations --country US

Local Data & Analytics

# 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

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

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

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

Background Daemon

Run GDELT sync as a background service:

# 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

Briefing Generation

Generate diplomatic intelligence briefings for any country using the gdelt-briefing.sh script. This leverages Claude Code with GDELT data to produce comprehensive country briefings.

Usage

# Basic usage - country name required
./gdelt-briefing.sh <country> [capital]

# Examples
./gdelt-briefing.sh Indonesia Jakarta
./gdelt-briefing.sh Ukraine Kyiv
./gdelt-briefing.sh Brazil

Output

Briefings are saved to briefings/<country>/ in the project directory.

Requirements

  • Claude Code CLI (claude) must be installed and configured
  • The /briefing skill must be available

Configuration

Configuration file: ~/.config/gdelt/config.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

# Clone repository
git clone https://github.com/neul-labs/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

# 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 
# 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 for details.

Links

About

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

docs.neullabs.com/gdelt-cli

Topics

osint large-language-models

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

GDELT CLI v0.1.0 Latest
Mar 20, 2026

Packages

 
 
 

Contributors

Languages