podcast-cli

A Unix-style CLI for querying Podcast Index. Designed for both humans and AI agents.

Install

npm install -g podcast-cli

Or run directly:

npx podcast-cli search "tech"

Setup

Get your free API keys at https://api.podcastindex.org, then configure:

podcast-cli config set --key YOUR_KEY --secret YOUR_SECRET

This saves credentials to ~/.config/podcast-cli/.env (file permissions 600).

Alternatively, use environment variables (takes precedence over config file):

export PODCAST_INDEX_API_KEY=your_key
export PODCAST_INDEX_API_SECRET=your_secret

Usage

Search podcasts

podcast-cli search "javascript"
podcast-cli search "AI news" --max 5
podcast-cli search "tech" --json | jq '.[].title'

Podcast details

podcast-cli info 920666

List episodes

podcast-cli episodes 920666
podcast-cli episodes 920666 --max 10

Trending

podcast-cli trending
podcast-cli trending --max 20 --lang en
podcast-cli trending --cat Technology

Pipeline composition

Commands are designed to work together via Unix pipes:

# Search and get details
podcast-cli search "tech" -q | podcast-cli info --stdin

# Get episodes for top 5 trending podcasts
podcast-cli trending -q | head -5 | podcast-cli episodes --stdin

# Extract audio URLs with jq
podcast-cli episodes 920666 --json | jq '.[].enclosureUrl'

Flags

| Flag | Description | |------|-------------| | --json | Output as JSON | | -q, --quiet | Output only IDs (one per line) | | --max <n> | Limit number of results | | --stdin | Read feed IDs from stdin | | --help | Show help | | --version | Show version |

Output

Default output is tab-separated text, one record per line. Works with grep, awk, cut, sort, and head.

• --json outputs structured JSON for programmatic use
• -q outputs bare IDs for piping between commands

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Invalid arguments | | 3 | Authentication error |