Add --format markdown for raw Markdown output (closes #1)

Adds a third output format for AI agent and LLM integration. When
--format markdown is used, raw Markdown is printed to stdout with no
Rich formatting, and ?format=markdown is passed to the MCP server.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mikeckennedy

.claude/settings.local.json

@@ -5,7 +5,9 @@
       "Bash(./venv/bin/python -m talk_python_cli.app status:*)",
       "Bash(./venv/bin/talkpython status:*)",
       "Bash(./venv/bin/pip install:*)",
-      "Bash(./venv/bin/talkpython:*)"
+      "Bash(./venv/bin/talkpython:*)",
+      "Bash(gh issue view:*)",
+      "Bash(pyrefly check:*)"
     ]
   }
 }

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 |
 

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')

tests/test_client.py

@@ -197,6 +197,35 @@ def test_json_format_adds_query_param(self, httpx_mock: HTTPXMock) -> None:
             assert 'format=json' in str(req.url)
         client.close()
 
+    def test_markdown_format_adds_query_param(self, httpx_mock: HTTPXMock) -> None:
+        md_url = f'{DEFAULT_URL}?format=markdown'
+        client = MCPClient(base_url=DEFAULT_URL, output_format='markdown')
+
+        httpx_mock.add_response(
+            method='POST',
+            url=md_url,
+            json=jsonrpc_result(
+                1,
+                {
+                    'protocolVersion': '2025-03-26',
+                    'capabilities': {'tools': {}},
+                    'serverInfo': {'name': 'test', 'version': '0.1'},
+                },
+            ),
+            headers={'mcp-session-id': 's1'},
+        )
+        httpx_mock.add_response(method='POST', url=md_url, status_code=202, headers={'mcp-session-id': 's1'})
+        httpx_mock.add_response(
+            method='POST',
+            url=md_url,
+            json=tool_result(3, '# Episode 535\n\nSome markdown content'),
+        )
+
+        client.call_tool('get_episodes')
+        for req in httpx_mock.get_requests():
+            assert 'format=markdown' in str(req.url)
+        client.close()
+
 
 class TestContextManager:
     """Verify MCPClient works as a context manager."""

tests/test_formatting.py

@@ -0,0 +1,38 @@
+"""Tests for output formatting."""
+
+from __future__ import annotations
+
+from talk_python_cli.formatting import display, display_markdown_raw
+
+
+class TestDisplayMarkdownRaw:
+    def test_prints_raw_content(self, capsys) -> None:
+        display_markdown_raw('# Hello\n\nSome **bold** text')
+
+        captured = capsys.readouterr()
+        assert captured.out == '# Hello\n\nSome **bold** text\n'
+
+    def test_no_rich_markup_in_output(self, capsys) -> None:
+        display_markdown_raw('## Heading\n- item 1\n- item 2')
+
+        captured = capsys.readouterr()
+        # Raw markdown should appear verbatim — no Rich panel borders or styling
+        assert '## Heading' in captured.out
+        assert '- item 1' in captured.out
+        assert '╭' not in captured.out  # no Rich panel border
+
+
+class TestDisplayRouting:
+    def test_markdown_format_routes_to_raw(self, capsys) -> None:
+        display('# Raw markdown', 'markdown')
+
+        captured = capsys.readouterr()
+        assert captured.out == '# Raw markdown\n'
+
+    def test_text_format_does_not_print_raw(self, capsys) -> None:
+        display('# Rendered', 'text')
+
+        captured = capsys.readouterr()
+        # Text mode uses Rich console, so raw '# Rendered' should NOT appear verbatim
+        # (Rich renders it as a heading without the # prefix)
+        assert '# Rendered' not in captured.out