newsdata-cli

A friendly command-line tool to query the newsdata.io news API straight from your terminal. Search the latest headlines, list available sources, and print results as a pretty table, JSON, or CSV — configurable via a .env file.

Built with Click and designed to work out of the box on the free newsdata.io plan.

Features

• 🔎 Search the latest news with keyword, country, language, and category filters
• 📰 List available news sources
• 📦 Three output formats: table (default), json, csv
• 🔁 Automatic pagination via the nextPage token (--max-results)
• 🧩 Choose exactly which fields to print with --fields
• 🛡️ Clear handling of invalid keys (401), rate limits (429), and empty results
• ⚙️ Configuration via environment variable or a local .env file

Installation

git clone https://github.com/your-username/newsdata-cli.git
cd newsdata-cli
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Configuration

The tool reads your API key from the NEWSDATA_API_KEY environment variable. Grab a free key at https://newsdata.io/register, then either export it:

export NEWSDATA_API_KEY=your_api_key_here

or copy the example dotenv file and fill it in (it is loaded automatically from the current directory):

cp .env.example .env
# edit .env and set NEWSDATA_API_KEY

Usage

# Latest news as a table (default)
python newsdata_cli.py news --query "artificial intelligence"

# Filter by country, language, and category
python newsdata_cli.py news -q bitcoin -c us,gb -l en --category business

# Get up to 25 results and print as JSON
python newsdata_cli.py news -q climate -n 25 --format json

# Export to CSV and save to a file
python newsdata_cli.py news -q "space" --format csv > space.csv

# Pick exactly which fields to show
python newsdata_cli.py news -q tech --fields title,pubDate,source_id,link

# List available sources for the US in English
python newsdata_cli.py sources -c us -l en

Run python newsdata_cli.py --help or python newsdata_cli.py news --help for the full option list.

Commands

Command	Description	Endpoint
news	Fetch the latest news articles	/news
sources	List available news sources	/sources

news options

Option	Description
-q, --query	Keywords or phrase to search for
-c, --country	Comma-separated country codes (e.g. us,gb)
-l, --language	Comma-separated language codes (e.g. en,es)
--category	Comma-separated categories (e.g. technology)
-n, --max-results	Max articles to return, following pagination (def. 10)
-f, --format	table, json, or csv (def. table)
--fields	Comma-separated fields for table/csv output

Free plan vs. paid plan

This tool is built entirely around endpoints and parameters available on the free newsdata.io tier (/news and /sources with q, country, language, category, and page-based pagination).

The following newsdata.io features require a paid plan and are intentionally not used by this CLI:

• Sentiment analysis (sentiment)
• AI-enriched fields (ai_tag, ai_region, ai_org, ai_summary)
• The historical /archive endpoint and long date ranges
• Advanced full-text query operators

If the API rejects a request with HTTP 403/422 (commonly an "upgrade your plan" response), the CLI reports it clearly instead of crashing.

License

MIT