Initial version of the talkpython CLI.

Author: mikeckennedy

README.md

@@ -1,2 +1,118 @@
-# talk-python-cli
-A CLI interface to run Inquiries against the TalkPythonToMe podcast data. 
+# Talk Python CLI
+
+A command-line interface for accessing [Talk Python to Me](https://talkpython.fm) podcast episodes, guest information, and [Talk Python Training](https://training.talkpython.fm) courses. Built on the Talk Python [MCP server](https://talkpython.fm/api/mcp), it gives you structured access to the full Talk Python catalog from your terminal.
+
+## Why use this?
+
+- **Automation** — Query episode data, guest info, and course catalogs from scripts and pipelines.
+- **LLM & AI integration** — Pipe JSON output directly into AI agents, RAG systems, or chat workflows.
+- **Quick lookups** — Search episodes, pull transcripts, and browse courses without leaving the terminal.
+
+## Installation
+
+Requires Python 3.12+.
+
+```bash
+# With uv (recommended)
+uv tool install talk-python-cli
+
+# With pip
+pip install talk-python-cli
+```
+
+This installs the `talkpython` command.
+
+## Quick start
+
+```bash
+# Search for episodes about FastAPI
+talkpython episodes search "FastAPI"
+
+# Get full details for a specific episode
+talkpython episodes get 535
+
+# Pull the transcript for an episode
+talkpython episodes transcript 535
+
+# List recent episodes
+talkpython episodes recent --limit 5
+
+# Search for a guest
+talkpython guests search "Hynek"
+
+# Browse all training courses
+talkpython courses list
+```
+
+## Commands
+
+### Episodes
+
+| Command | Description |
+|---------|-------------|
+| `talkpython episodes search <query> [--limit N]` | Search episodes by keyword (default limit: 10) |
+| `talkpython episodes get <show_id>` | Get full details for an episode |
+| `talkpython episodes list` | List all episodes |
+| `talkpython episodes recent [--limit N]` | Get the most recent episodes |
+| `talkpython episodes transcript <show_id>` | Get the plain-text transcript |
+| `talkpython episodes transcript-vtt <show_id>` | Get the WebVTT transcript (with timestamps) |
+
+### Guests
+
+| Command | Description |
+|---------|-------------|
+| `talkpython guests search <query> [--limit N]` | Search guests by name |
+| `talkpython guests get <guest_id>` | Get details for a specific guest |
+| `talkpython guests list` | List all guests, sorted by number of appearances |
+
+### Courses
+
+| Command | Description |
+|---------|-------------|
+| `talkpython courses search <query> [--course_id N]` | Search courses, chapters, and lectures |
+| `talkpython courses get <course_id>` | Get full course details including chapters and lectures |
+| `talkpython courses list` | List all available training courses |
+
+## Output formats
+
+The CLI auto-detects the best output format:
+
+- **Interactive terminal** — Rich-formatted Markdown with styled panels and color.
+- **Piped / redirected** — Compact JSON, ready for processing.
+
+Override the default with `--format`:
+
+```bash
+# Force JSON output in the terminal
+talkpython --format json episodes search "async"
+
+# Force rich text output even when piping
+talkpython --format text episodes recent | less -R
+```
+
+## Piping JSON to other tools
+
+Because the CLI outputs JSON automatically when piped, it integrates naturally with tools like `jq`, `llm`, or your own scripts:
+
+```bash
+# Extract episode titles with jq
+talkpython episodes search "testing" | jq '.title'
+
+# Feed episode data into an LLM
+talkpython episodes get 535 | llm "Summarize this podcast episode"
+
+# Grab a transcript for RAG ingestion
+talkpython episodes transcript 535 | your-rag-pipeline ingest
+```
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `--format text\|json` | Force output format (auto-detected by default) |
+| `--url <mcp-url>` | Override the MCP server URL (default: `https://talkpython.fm/api/mcp`) |
+| `--version`, `-V` | Show version |
+
+## License
+
+MIT

pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "talk-python-cli"
+version = "0.1.0"
+description = "CLI for the Talk Python to Me podcast and courses"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" },
+]
+dependencies = [
+    "cyclopts>=3.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+]
+
+[project.scripts]
+talkpython = "talk_python_cli.app:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.34",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/talk_python_cli"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

pyrefly.toml

@@ -0,0 +1,45 @@
+###### configuring what to type check and where to import from
+
+# check all files in "."
+project-includes = ["."]
+# exclude dotfiles
+project-excludes = ["**/.[!/.]*", "**/*venv/**"]
+# perform an upward search for `.gitignore`, `.ignore`, and `.git/info/exclude`, and
+# add those to `project-excludes` automatically
+use-ignore-files = true
+# import project files from "src" (main package) and "." (tests)
+search-path = ["src", "."]
+# let Pyrefly try to guess your search path
+disable-search-path-heuristics = false
+# do not include any third-party packages (except those provided by an interpreter)
+site-package-path = []
+
+###### configuring your python environment
+
+python-platform = "darwin"
+# assume the Python version we're using is 3.14, without querying an interpreter
+python-version = "3.14"
+# is Pyrefly disallowed from querying for an interpreter to automatically determine your
+# `python-platform`, `python-version`, and extra entries to `site-package-path`?
+skip-interpreter-query = false
+# query the default Python interpreter on your system, if installed and `python_platform`,
+# `python-version`, or `site-package-path` are unset.
+# python-interpreter = null # this is commented out because there are no `null` values in TOML
+
+#### configuring your type check settings
+
+# wildcards for which Pyrefly will unconditionally replace the import with `typing.Any`
+replace-imports-with-any = []
+# wildcards for which Pyrefly will replace the import with `typing.Any` if it can't be found
+ignore-missing-imports = []
+# should Pyrefly skip type checking if we find a generated file?
+ignore-errors-in-generated-code = false
+# what should Pyrefly do when it encounters a function that is untyped?
+untyped-def-behavior = "check-and-infer-return-type"
+# can Pyrefly recognize ignore directives other than `# pyrefly: ignore` and `# type: ignore`
+permissive-ignores = false
+
+[errors]
+# this is an empty table, meaning all errors are enabled by default
+
+# no `[[sub-config]]` entries are included, since there are none by default

ruff.toml

@@ -0,0 +1,43 @@
+# [ruff]
+line-length = 120
+format.quote-style = "single"
+
+# Enable Pyflakes `E` and `F` codes by default.
+lint.select = ["E", "F", "I"]
+lint.ignore = []
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    ".env",
+    ".venv",
+    "venv",
+    "typings/**/*.pyi",
+]
+lint.per-file-ignores = { }
+
+# Allow unused variables when underscore-prefixed.
+# dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+# Assume Python 3.14.
+target-version = "py314"
+
+#[tool.ruff.mccabe]
+## Unlike Flake8, default to a complexity level of 10.
+lint.mccabe.max-complexity = 10

src/talk_python_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Talk Python to Me CLI — query podcast episodes, guests, and courses."""
+
+__version__ = '0.1.0'

src/talk_python_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m talk_python_cli``."""
+
+from talk_python_cli.app import main
+
+main()

src/talk_python_cli/app.py

@@ -0,0 +1,91 @@
+"""Root Cyclopts application with global options."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Literal
+
+import cyclopts
+
+from talk_python_cli import __version__
+from talk_python_cli.client import DEFAULT_URL, MCPClient
+from talk_python_cli.formatting import is_tty, print_error
+
+# ── Shared state ─────────────────────────────────────────────────────────────
+# The meta-app handler stores the client here so command modules can access it.
+_client: MCPClient | None = None
+
+
+def get_client() -> MCPClient:
+    """Return the active MCPClient (set by the meta-app launcher)."""
+    assert _client is not None, 'MCPClient not initialised — this is a bug'
+    return _client
+
+
+# ── Root app ─────────────────────────────────────────────────────────────────
+app = cyclopts.App(
+    name='talkpython',
+    help='CLI for the Talk Python to Me podcast and courses.\n\n'
+    'Query episodes, guests, transcripts, and training courses\n'
+    'from the Talk Python MCP server.',
+    version=__version__,
+    version_flags=['--version', '-V'],
+)
+
+# ── Register sub-apps (imported here to avoid circular imports) ──────────────
+from talk_python_cli.courses import courses_app  # noqa: E402
+from talk_python_cli.episodes import episodes_app  # noqa: E402
+from talk_python_cli.guests import guests_app  # noqa: E402
+
+app.command(episodes_app)
+app.command(guests_app)
+app.command(courses_app)
+
+
+# ── Meta-app: handles global options before dispatching to sub-commands ──────
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
+    format: Annotated[
+        Literal['text', 'json'],
+        cyclopts.Parameter(
+            name='--format',
+            help="Output format: 'text' (rich Markdown) or 'json'. Defaults to 'json' when stdout is piped.",
+        ),
+    ] = None,  # type: ignore
+    url: Annotated[
+        str,
+        cyclopts.Parameter(
+            name='--url',
+            help='MCP server URL.',
+            show_default=True,
+        ),
+    ] = DEFAULT_URL,
+) -> None:
+    global _client
+
+    # Auto-detect: default to json when piped, text when interactive
+    if format is None:
+        format = 'text' if is_tty() else 'json'
+
+    _client = MCPClient(base_url=url, output_format=format)
+    try:
+        app(tokens)
+    except Exception as exc:
+        print_error(str(exc))
+        sys.exit(1)
+    finally:
+        _client.close()
+        _client = None
+
+
+# ── Entrypoint ───────────────────────────────────────────────────────────────
+def main() -> None:
+    """CLI entrypoint — called by the ``talkpython`` console script."""
+    try:
+        app.meta()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print_error(str(exc))
+        sys.exit(1)