Podscan REST API — search 51M+ podcast episodes and 4.4M+ podcasts.
Full transcripts, AI-extracted entities, mentions, brand-safety analysis.
Learn more at Podscan.
Printed by @gregvanhorn (Greg Van Horn).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your access token from your API provider's developer portal, then store it:
podscan-pp-cli auth set-token YOUR_TOKEN_HERE
Or set it via environment variable:
export PODSCAN_BEARER_AUTH="your-token-here"
3. Verify Setup
podscan-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
podscan-pp-cli alerts list
Usage
Run podscan-pp-cli --help for the full command reference and flag list.
Commands
alerts
Manage alerts
podscan-pp-cli alerts create - Create a new alertpodscan-pp-cli alerts delete - Delete an alertpodscan-pp-cli alerts get - Get an alertpodscan-pp-cli alerts list - List configured alerts
categories
Manage categories
podscan-pp-cli categories list - List all podcast categories
episodes
Manage episodes
podscan-pp-cli episodes get - Get an episode by IDpodscan-pp-cli episodes search - Search episodes by transcript content
exports
Manage exports
podscan-pp-cli exports download - Download an export filepodscan-pp-cli exports list-episode - List daily episode export filespodscan-pp-cli exports list-podcast - List podcast catalog export files
podcasts
Manage podcasts
podscan-pp-cli podcasts get - Get a podcast by IDpodscan-pp-cli podcasts search - Search podcasts by name or description
Output Formats
# Human-readable table (default in terminal, JSON when piped)
podscan-pp-cli alerts list
# JSON for scripting and agents
podscan-pp-cli alerts list --json
# Filter to specific fields
podscan-pp-cli alerts list --json --select id,name,status
# Dry run — show the request without sending
podscan-pp-cli alerts list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
podscan-pp-cli alerts list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
podscan-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/podscan-pp-cli/config.toml
Environment variables:
| Name | Kind | Required | Description |
|---|
PODSCAN_BEARER_AUTH | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
podscan-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $PODSCAN_BEARER_AUTH
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press