Merge branch 'main' of https://github.com/talkpython/talk-python-cli

Author: mikeckennedy

.claude/settings.local.json

@@ -6,7 +6,10 @@
       "Bash(./venv/bin/talkpython status:*)",
       "Bash(./venv/bin/pip install:*)",
       "Bash(./venv/bin/talkpython:*)",
-      "WebFetch(domain:badge.fury.io)"
+      "WebFetch(domain:badge.fury.io)",
+      "Bash(gh issue view:*)",
+      "Bash(pyrefly check:*)",
+      "Bash(uv lock:*)"
     ]
   }
 }

.github/workflows/syntax-check.yml

@@ -0,0 +1,46 @@
+name: Python Syntax Check
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    branches: ['**']
+
+jobs:
+  syntax-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install ruff
+        run: uv tool install ruff
+
+      - name: Get changed Python files
+        id: changed-files
+        uses: tj-actions/changed-files@v45
+        with:
+          files: |
+            **/*.py
+
+      - name: Run ruff format check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          uv tool run ruff format --check ${{ steps.changed-files.outputs.all_changed_files }}
+
+      - name: Run ruff check
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          uv tool run ruff check ${{ steps.changed-files.outputs.all_changed_files }}

CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md — Agent Instructions for talk-python-cli
+
+## Project Overview
+
+CLI client for the Talk Python to Me podcast and Talk Python Training courses.
+Wraps a remote MCP server (`https://talkpython.fm/api/mcp`) using JSON-RPC 2.0
+over HTTP. The CLI is a **thin client** — all business logic lives on the server.
+The CLI handles argument parsing, HTTP transport, and output formatting.
+
+Published on PyPI as `talk-python-cli`. Entry point: `talkpython`.
+
+## Critical Rules
+
+- **Use `uv pip install`, never `pip install`.**
+- **Virtual environment is `./venv`, NOT `./.venv`.**
+- **After every code edit, run: `ruff format && ruff check --fix`**
+- **Use `pyrefly check` to validate type information after changes.**
+- Do not add unnecessary abstractions, comments, or docstrings to unchanged code.
+- **Update `change-log.md` after every major change** (new features, breaking changes, notable fixes). Follow the [Keep a Changelog](https://keepachangelog.com/) format already in use.
+
+## Build & Run
+
+```bash
+# Activate venv
+source venv/bin/activate
+
+# Install in editable mode
+uv pip install -e ".[dev]"
+
+# Run CLI
+talkpython --help
+talkpython episodes search "fastapi"
+talkpython status
+
+# Run tests
+pytest
+
+# Lint & format (ALWAYS after edits)
+ruff format && ruff check --fix
+
+# Type check (ALWAYS after edits)
+pyrefly check
+```
+
+## Project Structure
+
+```
+src/talk_python_cli/
+  __init__.py       # Version from importlib.metadata
+  __main__.py       # python -m entry point
+  app.py            # Root Cyclopts app, global options, meta-handler, status cmd
+  client.py         # MCPClient: httpx-based JSON-RPC 2.0 client
+  formatting.py     # Rich output: Markdown panels (text) or JSON
+  episodes.py       # Episode commands (search, get, list, recent, transcript)
+  guests.py         # Guest commands (search, get, list)
+  courses.py        # Course commands (search, get, list)
+
+tests/
+  conftest.py       # Shared fixtures, JSON-RPC response builders
+  test_client.py    # MCPClient tests
+  test_episodes.py  # Episode command tests
+  test_guests.py    # Guest command tests
+  test_courses.py   # Course command tests
+```
+
+## Architecture & Key Patterns
+
+### CLI Framework: Cyclopts (not Click, not Typer)
+
+- Root app in `app.py` with sub-apps for episodes, guests, courses.
+- **Meta-app launcher** (`@app.meta.default`): intercepts all invocations to
+  process global options (`--format`, `--url`) before dispatching to subcommands.
+- Parameters use `Annotated[type, cyclopts.Parameter(...)]` for docs/defaults.
+- Cyclopts auto-converts snake_case commands to kebab-case (e.g. `transcript_vtt` → `transcript-vtt`).
+
+### Client Pattern
+
+- `MCPClient` in `client.py` wraps httpx for JSON-RPC 2.0 over HTTP.
+- Lazy initialization: `_ensure_initialized()` runs MCP handshake on first call.
+- Session ID tracked via `Mcp-Session-Id` response header.
+- `call_tool(tool_name, arguments)` is the only public API for MCP tool calls.
+- Output format sent as URL query param: `?format=json` when JSON mode.
+- No authentication required (public API).
+
+### Lazy Client Access (avoids circular imports)
+
+Each command module retrieves the client via a local helper:
+```python
+def _client():
+    from talk_python_cli.app import get_client
+    return get_client()
+```
+This deferred import avoids circular dependency since `app.py` imports the command modules.
+
+### Output Formatting
+
+- `display(content, format)` in `formatting.py` routes to markdown or JSON renderer.
+- Text mode: Rich Markdown panel with "Talk Python" theme (cyan border, monokai code).
+- JSON mode on TTY: pretty-printed with syntax highlighting.
+- JSON mode piped: compact single-line JSON for scripting.
+
+### Adding a New Command
+
+1. Add function in the appropriate module (`episodes.py`, `guests.py`, `courses.py`).
+2. Decorate with `@sub_app.default` or just define as a regular function in the sub-app.
+3. Call `_client().call_tool('tool_name', {'arg': value})` to invoke the MCP tool.
+4. Pass result to `display(result, _client().output_format)`.
+5. Add tests in the corresponding test file using `pytest-httpx` mocks.
+
+### Adding a New Command Group
+
+1. Create `src/talk_python_cli/newgroup.py` with a `cyclopts.App(name='newgroup')`.
+2. Register in `app.py`: `app.command(newgroup.sub_app)`.
+3. Create `tests/test_newgroup.py`.
+
+## Testing
+
+- Framework: **pytest** with **pytest-httpx** for HTTP mocking.
+- `conftest.py` provides helpers: `jsonrpc_result()`, `tool_result()`, `add_init_responses()`.
+- Every test must call `add_init_responses(httpx_mock)` before making MCP client calls.
+- Tests verify JSON-RPC request structure, argument passing, and response handling.
+
+## Dependencies
+
+| Package      | Purpose                        |
+|-------------|--------------------------------|
+| cyclopts    | CLI framework (commands, args) |
+| httpx       | HTTP client for MCP calls      |
+| rich        | Terminal output formatting      |
+| pytest      | Testing (dev)                  |
+| pytest-httpx| HTTP mocking in tests (dev)    |
+
+Build system: **hatchling**. Package manager: **uv**.
+
+## Config Files
+
+- `pyproject.toml` — Package metadata, dependencies, entry points, build config
+- `ruff.toml` — Line length 120, single quotes, target Python 3.14
+- `pyrefly.toml` — Type checker config, search path includes `src/`
+- `uv.lock` — Locked dependencies (committed)
+
+## Style Conventions
+
+- Line length: 120
+- Quotes: single quotes
+- Modern Python type syntax: `dict | None` not `Optional[dict]`
+- `from __future__ import annotations` in all modules
+- Private helpers prefixed with `_`
+- Minimal docstrings: only on public functions/classes
+- Python target: 3.12+ (currently targeting 3.14 in tooling)

README.md

@@ -84,41 +84,55 @@ talkpython courses list
 
 ## Output formats
 
-The CLI auto-detects the best output format:
+The CLI supports three output formats via `--format`:
 
-- **Interactive terminal** — Rich-formatted Markdown with styled panels and color.
-- **Piped / redirected** — Compact JSON, ready for processing.
-
-Override the default with `--format`:
+- **`text`** (default) — Rich-formatted Markdown with styled panels and color for human reading.
+- **`json`** — Structured JSON, pretty-printed on a TTY or compact when piped.
+- **`markdown`** — Raw Markdown output with no Rich formatting. Ideal for piping into AI agents, LLMs, and automation tools that consume Markdown natively.
 
 ```bash
 # Force JSON output in the terminal
 talkpython --format json episodes search "async"
 
+# Raw Markdown for AI agents and LLM pipelines
+talkpython --format markdown episodes get 535
+
 # Force rich text output even when piping
 talkpython --format text episodes recent | less -R
 ```
 
+## Agentic AI and LLM integration
+
+Use `--format markdown` when feeding output to AI agents, LLMs, or RAG pipelines. This gives you clean, raw Markdown without terminal styling — exactly what language models expect:
+
+```bash
+# Feed an episode summary to an LLM
+talkpython --format markdown episodes get 535 | llm "Summarize this podcast episode"
+
+# Grab a transcript for RAG ingestion
+talkpython --format markdown episodes transcript 535 | your-rag-pipeline ingest
+
+# Pipe course details into an AI agent
+talkpython --format markdown courses get 57 | your-agent process
+```
+
 ## 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:
+The `--format json` output integrates naturally with tools like `jq` 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"
+talkpython --format json episodes search "testing" | jq '.title'
 
-# Grab a transcript for RAG ingestion
-talkpython episodes transcript 535 | your-rag-pipeline ingest
+# Process structured data in a script
+talkpython --format json episodes recent | python process_episodes.py
 ```
 
 ## Global options
 
 | Option | Description |
 |--------|-------------|
-| `--format text\|json` | Force output format (auto-detected by default) |
+| `--format text\|json\|markdown` | Output format: `text` (rich), `json`, or `markdown` (raw) |
 | `--url <mcp-url>` | Override the MCP server URL (default: `https://talkpython.fm/api/mcp`) |
 | `--version`, `-V` | Show version |
 

change-log.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-07
+
+### Added
+- `--format markdown` output mode for raw Markdown without Rich formatting, ideal for AI agents, LLMs, and RAG pipelines
+- New "Agentic AI and LLM integration" section in README
+- `display_markdown_raw()` in `formatting.py` for plain stdout output
+- Tests for markdown format: query param propagation, raw output, and display routing
+
+### Changed
+- `--format` flag now accepts `text`, `json`, or `markdown` (was `text` or `json`)
+- MCP client sends `?format=markdown` query param to server when markdown format is selected
+- README "Output formats" and "Piping JSON to other tools" sections updated for the new format
+
+---
+
 ## [0.1.2] - 2026-02-07
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "talk-python-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "CLI for the Talk Python to Me podcast and courses"
 requires-python = ">=3.12"
 license = "MIT"

src/talk_python_cli/__init__.py

@@ -2,4 +2,4 @@
 
 from importlib.metadata import version
 
-__version__ = version("talk-python-cli")
+__version__ = version('talk-python-cli')

src/talk_python_cli/app.py

@@ -82,10 +82,10 @@ def status() -> None:
 def launcher(
     *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
     format: Annotated[
-        Literal['text', 'json'],
+        Literal['text', 'json', 'markdown'],
         cyclopts.Parameter(
             name='--format',
-            help="Output format: 'text' (rich Markdown) or 'json'.",
+            help="Output format: 'text' (rich Markdown), 'json', or 'markdown' (raw).",
         ),
     ] = 'text',
     url: Annotated[

src/talk_python_cli/client.py

@@ -46,8 +46,8 @@ def _next_id(self) -> int:
         return self._msg_id
 
     def _url(self) -> str:
-        if self.output_format == 'json':
-            return f'{self.base_url}?format=json'
+        if self.output_format in ('json', 'markdown'):
+            return f'{self.base_url}?format={self.output_format}'
         return self.base_url
 
     def _post(self, payload: dict) -> httpx.Response:

src/talk_python_cli/formatting.py

@@ -39,10 +39,17 @@ def display(content: str, output_format: str) -> None:
     """Route content to the appropriate renderer."""
     if output_format == 'json':
         display_json(content)
+    elif output_format == 'markdown':
+        display_markdown_raw(content)
     else:
         display_markdown(content)
 
 
+def display_markdown_raw(content: str) -> None:
+    """Print raw Markdown content to stdout without any Rich formatting."""
+    print(content)
+
+
 def display_markdown(content: str) -> None:
     """Render Markdown content with Rich, wrapped in a styled panel."""
     md = Markdown(content, code_theme='monokai')
@@ -61,7 +68,7 @@ def display_json(content: str) -> None:
     """Output JSON content — pretty-printed if on a TTY, raw otherwise."""
     try:
         data = json.loads(content)
-    except json.JSONDecodeError, TypeError:
+    except (json.JSONDecodeError, TypeError):
         # Server may have returned Markdown even though JSON was requested;
         # fall back to printing the raw text.
         console.print(content)