Podscan CLI

Podscan REST API — search 51M+ podcast episodes and 4.4M+ podcasts. Full transcripts, AI-extracted entities, mentions, brand-safety analysis.

Learn more at Podscan.

Created 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 alert
• podscan-pp-cli alerts delete - Delete an alert
• podscan-pp-cli alerts get - Get an alert
• podscan-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 ID
• podscan-pp-cli episodes search - Search episodes by transcript content

exports

Manage exports

• podscan-pp-cli exports download - Download an export file
• podscan-pp-cli exports list-episode - List daily episode export files
• podscan-pp-cli exports list-podcast - List podcast catalog export files

podcasts

Manage podcasts

• podscan-pp-cli podcasts get - Get a podcast by ID
• podscan-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