pp-podcast-goat

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/podcast-goat/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Podcast GOAT — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `podcast-goat-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install podcast-goat --cli-only
   ```
2. Verify: `podcast-goat-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/podcast-goat/cmd/podcast-goat-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for podcast-goat when an agent needs to read or quote from a long-form podcast and you already subscribe to the show. The CLI walks your member cookies first, falls back to free YouTube/Substack/RSS sources, and only spends money on spoken.md or audio transcription when nothing free works. The MCP surface makes it the canonical podcast adapter for Claude Code agents — every command is an MCP tool, every read is annotated `mcp:read-only`.

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

### Anti-triggers

Skip podcast-goat for:

- **Audio downloads.** This CLI never writes audio to disk. Use `yt-dlp` or your podcast app directly.
- **Paywall bypass.** Cookie-tier adapters replay your own logged-in session for shows you already subscribe to. Do not route a request through here to read content the user has not paid for.
- **LLM summarization or analysis.** This CLI ships canonical markdown to your agent. The summarization happens in the agent, not here.
- **Real-time live transcription.** Audio-pipeline (`whisperapi`) is a deferred v0.2 path; for live captions reach for a streaming Deepgram client instead.
- **Editing or annotating transcripts in place.** Output is read-only; persist your annotations elsewhere.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Cross-source corpus that compounds
- **`magic`** — Bundle top-N cached transcripts about a topic into one markdown file an agent can summarize in a single call.

  _Replaces the chip-supply-chain.fly.dev copy-paste workflow with one command. Reach for this when the agent needs cross-episode synthesis._

  ```bash
  podcast-goat-pp-cli magic 'AI chip supply chain' --out ~/chip-supply-chain.md
  ```
- **`episode get --explain`** — Dry-run shows which source tier will fire and why earlier tiers were skipped, with projected cost before any paid call.

  _Lets agents preview cost and source attribution before committing. Reach for this before any paid run._

  ```bash
  podcast-goat-pp-cli episode get https://www.hubermanlab.com/episode/example --explain
  ```
- **`episode quote`** — FTS5 phrase search returns the matched segment plus N surrounding segments preserving the canonical speaker shape and deeplink timestamp.

  _Grep your podcast memory in 5 seconds. Reach for this when you remember a half-citation and need the exact line back._

  ```bash
  podcast-goat-pp-cli episode quote 'pricing power' -C 3 --json
  ```
- **`source compare`** — For an episode resolvable on multiple sources, fetch all available adapters and diff segment count, token count, distinct speakers, label confidence.

  _Reveals when free sources are good enough vs when paid is needed. Reach for this before recommending an upstream source._

  ```bash
  podcast-goat-pp-cli source compare https://www.acquired.fm/episodes/vanguard --json
  ```
- **`speakers list`** — Aggregate speaker names across the cached corpus with episode counts, optionally filtered by show.

  _Answers 'what do I have on Senra/Buffett/Karpathy'. Reach for this when building a synthesis prompt._

  ```bash
  podcast-goat-pp-cli speakers list --show acquired --json
  ```

### Multilingual reach
- **`episode get --bilingual`** — yt-dlp dual-language auto-subs, greedy nearest-neighbor alignment, emits one markdown file with paired Chinese + auto-translated English per turn.

  _Makes Mandarin-only podcasts (e.g., Xiaojun) usable for English-reading agents in one step._

  ```bash
  podcast-goat-pp-cli episode get 'https://www.youtube.com/watch?v=EXAMPLE' --bilingual zh-Hans,en
  ```

### Agent-native plumbing
- **`auth services`** — One-row-per-service table of cookie age, expiry, last-fetch result, with remediation hint when stale.

  _Cookies decay silently. Reach for this before a batch run to confirm member access still works._

  ```bash
  podcast-goat-pp-cli auth services --json
  ```
- **`budget show --by-show`** — Pivot spend.jsonl joined to episodes by URL; group by show, provider, month to attribute cost.

  _Shows which subscriptions are paying off and which shows still cost money. Reach for this monthly._

  ```bash
  podcast-goat-pp-cli budget show --by-show --since 30 --json
  ```

## Command Reference

**episode** — Pull, search, and inspect podcast episode transcripts

- `podcast-goat-pp-cli episode get` — Fetch one transcript by URL via the cookie -> free -> paid dispatch chain
- `podcast-goat-pp-cli episode latest` — Pull the most recent episode for a subscribed feed


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
podcast-goat-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes

### Hermes / Claude / agent workflows

The three recipes below cover the end-to-end agent workflows this CLI was
built for. Pattern-match against user phrasing — the trigger phrases at the
end of each recipe are the kind of natural language an agent should respond
to by reaching for this recipe instead of fetching transcripts manually.

#### Monday-morning batch pull → topic bundle → agent summarize

```bash
# One-time setup (if not already done):
podcast-goat-pp-cli auth set-key --provider spoken --value $SPOKEN_API_KEY
podcast-goat-pp-cli auth login-service --service spotify    # if user has Spotify Premium

# The actual workflow:
podcast-goat-pp-cli episode batch \
  https://www.dwarkesh.com/p/andrej-karpathy \
  https://open.spotify.com/episode/<id> \
  https://www.acquired.fm/episodes/<slug> \
  --json

podcast-goat-pp-cli magic "AI chip supply chain" --limit 5 --out /tmp/bundle.md
# Then: ask the user's preferred LLM to summarize /tmp/bundle.md
```

Pulls multiple episodes in parallel (default 3 concurrent), caches each, then bundles cached episodes matching the topic into one YAML-front-matter markdown file ready for one-shot agent summarization. Each episode in the bundle carries `source`, `show`, `host`, `date`, `provider`, `cost` so