Update README for latest changes

https://gistpreview.github.io/?9b3fe747343d32c95a8565ef1f8b6e11/index.html

Refs #3, #4

Author: simonw

README.md

@@ -5,7 +5,7 @@
 [![Tests](https://github.com/simonw/claude-code-publish/workflows/Test/badge.svg)](https://github.com/simonw/claude-code-publish/actions?query=workflow%3ATest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/simonw/claude-code-publish/blob/main/LICENSE)
 
-Convert Claude Code `session.json` files to clean, mobile-friendly HTML pages with pagination.
+Convert Claude Code session files (JSON or JSONL) to clean, mobile-friendly HTML pages with pagination.
 
 [Example transcript](https://static.simonwillison.net/static/2025/claude-code-microjs/index.html) produced using this tool.
 
@@ -23,108 +23,134 @@ uvx claude-code-publish --help
 
 ## Usage
 
-When using [Claude Code for web](https://claude.ai/code) you can export your session as a `session.json` file using the `teleport` command (and then hunting around on disk).
+This tool converts Claude Code session files into browseable multi-page HTML transcripts.
 
-This tool converts that JSON into a browseable multi-page HTML transcript.
+There are three commands available:
 
-The quickest way to view a recent session is to import it directly and open in your browser:
+- `local` (default) - select from local Claude Code sessions stored in `~/.claude/projects`
+- `web` - select from web sessions via the Claude API
+- `json` - convert a specific JSON or JSONL session file
+
+The quickest way to view a recent local session:
 
 ```bash
-claude-code-publish import --open
+claude-code-publish
 ```
 
 This shows an interactive picker to select a session, generates HTML, and opens it in your default browser.
 
-For a local session file:
-
-```bash
-claude-code-publish session.json -o output-directory/
-```
-
-This will generate:
-- `index.html` - an index page with a timeline of prompts and commits
-- `page-001.html`, `page-002.html`, etc. - paginated transcript pages
+### Output options
 
-### Options
+All commands support these options:
 
-- `-o, --output DIRECTORY` - output directory (default: current directory)
+- `-o, --output DIRECTORY` - output directory (default: writes to temp dir and opens browser)
+- `-a, --output-auto` - auto-name output subdirectory based on session ID or filename
 - `--repo OWNER/NAME` - GitHub repo for commit links (auto-detected from git push output if not specified)
-- `--open` - open the generated `index.html` in your default browser
+- `--open` - open the generated `index.html` in your default browser (default if no `-o` specified)
 - `--gist` - upload the generated HTML files to a GitHub Gist and output a preview URL
-- `--json` - include the original JSON session file in the output directory
+- `--json` - include the original session file in the output directory
 
-### Publishing to GitHub Gist
+The generated output includes:
+- `index.html` - an index page with a timeline of prompts and commits
+- `page-001.html`, `page-002.html`, etc. - paginated transcript pages
 
-Use the `--gist` option to automatically upload your transcript to a GitHub Gist and get a shareable preview URL.
+### Local sessions
 
-If you use that with the `import` command with no other options you can directly select a session to publish to a Gist:
+Local Claude Code sessions are stored as JSONL files in `~/.claude/projects`. Run with no arguments to select from recent sessions:
 
 ```bash
-claude-code-publish import --gist
+claude-code-publish
+# or explicitly:
+claude-code-publish local
 ```
-The `--gist` option is available for other commands too:
+
+Use `--limit` to control how many sessions are shown (default: 10):
 
 ```bash
-claude-code-publish session.json --gist
-claude-code-publish import session_01BU6ZZoB7zTHrh9DAspF5hj --gist
+claude-code-publish local --limit 20
 ```
 
-Each of these will output something like:
-```
-Gist: https://gist.github.com/username/abc123def456
-Preview: https://gistpreview.github.io/?abc123def456/index.html
-Files: /var/folders/.../session-id
+### Web sessions
+
+Import sessions directly from the Claude API:
+
+```bash
+# Interactive session picker
+claude-code-publish web
+
+# Import a specific session by ID
+claude-code-publish web SESSION_ID
+
+# Import and publish to gist
+claude-code-publish web SESSION_ID --gist
 ```
 
-The preview URL uses [gistpreview.github.io](https://gistpreview.github.io/) to render your HTML gist. The tool automatically injects JavaScript to fix relative links when served through gistpreview.
+On macOS, API credentials are automatically retrieved from your keychain (requires being logged into Claude Code). On other platforms, provide `--token` and `--org-uuid` manually.
+
+### JSON/JSONL files
 
-When using `--gist` without `-o`, files are written to a temporary directory (shown in the output). You can combine both options to keep a local copy:
+Convert a specific session file directly:
 
 ```bash
-claude-code-publish session.json -o ./my-transcript --gist
+claude-code-publish json session.json -o output-directory/
+claude-code-publish json session.jsonl --open
 ```
 
-**Requirements:** The `--gist` option requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated (`gh auth login`).
+When using [Claude Code for web](https://claude.ai/code) you can export your session as a `session.json` file using the `teleport` command.
 
-### Including the JSON source
+### Auto-naming output directories
 
-Use the `--json` option to include the original session JSON file in the output directory:
+Use `-a/--output-auto` to automatically create a subdirectory named after the session:
 
 ```bash
-claude-code-publish session.json -o ./my-transcript --json
-```
+# Creates ./session_ABC123/ subdirectory
+claude-code-publish web SESSION_ABC123 -a
 
-This will output:
+# Creates ./transcripts/session_ABC123/ subdirectory
+claude-code-publish web SESSION_ABC123 -o ./transcripts -a
 ```
-JSON: ./my-transcript/session_ABC.json (245.3 KB)
+
+### Publishing to GitHub Gist
+
+Use the `--gist` option to automatically upload your transcript to a GitHub Gist and get a shareable preview URL:
+
+```bash
+claude-code-publish --gist
+claude-code-publish web --gist
+claude-code-publish json session.json --gist
 ```
 
-The JSON file preserves its original filename. This is useful for archiving the source data alongside the HTML output.
+This will output something like:
+```
+Gist: https://gist.github.com/username/abc123def456
+Preview: https://gistpreview.github.io/?abc123def456/index.html
+Files: /var/folders/.../session-id
+```
 
-## Importing from Claude API
+The preview URL uses [gistpreview.github.io](https://gistpreview.github.io/) to render your HTML gist. The tool automatically injects JavaScript to fix relative links when served through gistpreview.
 
-You can import sessions directly from the Claude API without needing to export a `session.json` file:
+Combine with `-o` to keep a local copy:
 
 ```bash
-# List available sessions
-claude-code-publish list-web
+claude-code-publish json session.json -o ./my-transcript --gist
+```
 
-# Import a specific session
-claude-code-publish import SESSION_ID -o output-directory/
+**Requirements:** The `--gist` option requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated (`gh auth login`).
 
-# Import with interactive session picker
-claude-code-publish import
+### Including the source file
 
-# Import and publish to gist
-claude-code-publish import SESSION_ID --gist
+Use the `--json` option to include the original session file in the output directory:
 
-# Import and save the JSON session data
-claude-code-publish import SESSION_ID --json
+```bash
+claude-code-publish json session.json -o ./my-transcript --json
 ```
 
-On macOS, the API credentials are automatically retrieved from your keychain (requires being logged into Claude Code). On other platforms, provide `--token` and `--org-uuid` manually.
+This will output:
+```
+JSON: ./my-transcript/session_ABC.json (245.3 KB)
+```
 
-The `--json` option for the import command saves the session data fetched from the API as `{session_id}.json` in the output directory.
+This is useful for archiving the source data alongside the HTML output.
 
 ## Development