CLI Reference¶
The full command-line interface for claude-code-log. This page is generated
directly from the Click command definitions in
claude_code_log/cli.py,
so it always matches the installed version.
Tip
You can see the same information at any time with claude-code-log --help.
claude-code-log¶
Convert Claude transcript JSONL files to HTML or Markdown.
Usage:
Options:
claude-code-log convert¶
Convert Claude transcript JSONL files to HTML or Markdown.
INPUT_PATH: Path to a Claude transcript JSONL file, directory containing JSONL files, or project path to convert. If not provided, defaults to ~/.claude/projects/ and --all-projects is used.
Usage:
Options:
--version Show the version and exit.
-o, --output PATH Output destination. Use '-' (or /dev/stdout)
to stream the rendered document to stdout
(status goes to stderr) for piping. With a
recognised file suffix
(.html/.md/.markdown/.json) treated as a
single output file; otherwise treated as a
directory root (and now also honoured for
--all-projects, where outputs land at
<output>/<project>/...). Pair with --expand-
paths to project back to the real on-disk
tree.
--expand-paths When set with --output and --all-projects,
expand each project's flat encoded dir name
(e.g. '-home-joe-project-A') back to its
real path under <output>/. Resolves the
encoded name via the cache's recorded `cwd`,
falling back to a peek of the first JSONL
when the cache is empty. Useful for
projecting transcripts into Obsidian-style
Markdown vaults.
--filter-path TEXT Restrict --all-projects to projects matching
a path prefix. With --expand-paths, the
prefix is matched against the expanded real
path AND truncated from the destination
(`/home/joe/project/A` with --filter-path
/home/joe lands at <output>/project/A/).
Without --expand-paths, matches the flat
encoded dir name (e.g. '-home-joe' selects
projects starting with '-home-joe-').
--open-browser Open the generated HTML file in the default
browser
--from-date TEXT Filter messages from this date/time (e.g.,
"2 hours ago", "yesterday", "2025-06-08")
--to-date TEXT Filter messages up to this date/time (e.g.,
"1 hour ago", "today", "2025-06-08 15:00")
--all-projects Process all projects in ~/.claude/projects/
hierarchy and create linked HTML files
--no-individual-sessions Skip generating individual session files
(combined transcript only). Back-compat
alias for --combined only.
--combined [yes|no|only] Control combined-vs-individual transcript
generation: 'yes' = both combined and per-
session files (default for --all-projects);
'no' = only per-session files (recommended
for Obsidian / vault use — combined is dead
weight; note a prior 'yes' run's combined
files are not deleted, use --clear-output to
sweep them); 'only' = only the combined file
(= --no-individual-sessions). When unset,
defaults to 'no' under --expand-paths
(Obsidian mode), else 'yes'.
--no-cache Disable caching and force reprocessing of
all files
--clear-cache Clear all cache directories before
processing
--clear-output, --clear-html Clear generated output files (HTML or
Markdown based on --format) and force
regeneration
--tui Launch interactive TUI for session browsing
and management
--projects-dir PATH Custom projects directory (default:
~/.claude/projects/). Useful for testing.
-f, --format [html|md|markdown|json]
Output format. Supports html, md/markdown,
or json. When omitted, inferred from the
--output file suffix
(.md/.markdown/.html/.json); otherwise
defaults to html.
--image-export-mode [placeholder|embedded|referenced]
Image export mode: placeholder (mark
position), embedded (base64), referenced
(PNG files). Default: embedded for HTML,
referenced for Markdown.
--page-size INTEGER Maximum messages per page for combined
transcript (default: 2000). Sessions are
never split across pages.
-j, --jobs INTEGER RANGE Worker processes for converting projects in
--all-projects mode (default: CPU count; 1
disables parallelism). Peak memory scales
with jobs x the largest stale project. Also
caps the per-project render fan-out, which
is on by default and controlled by
$CLAUDE_CODE_LOG_RENDER_JOBS (1 or 'off' to
disable, auto, or a worker count). [x>=1]
--provider NAME Load a single session from a registered
provider (for example, codex).
--session-id TEXT Export a single session by ID (full ID or
prefix). Project path is optional — looks up
the session globally via cache.
--depth [session|user|assistant|agent|tool|hook]
How deep into the message hierarchy to
render (session > user > assistant > agent >
tool > hook); output stops at the named
level. DEFAULT: tool. session: session
structure only (headers/nav); user: user
prompts and steering only; assistant: user +
assistant messages; agent: + sub-agents and
key tool signals; tool: + tools, cleaned of
system/hook noise (default); hook:
everything, including hooks and system
notices. Mutually exclusive with the
deprecated --detail.
--detail [full|high|low|minimal|user-only]
DEPRECATED (removed in 2.0) — prefer
--depth. Detail level for output. full
(=--depth hook): everything; high (=--depth
tool): detailed but cleaned (no system/hook
noise); low (=--depth agent): interaction-
focused + key signals; minimal (=--depth
assistant): user + assistant messages only;
user-only (=--depth user): only user prompts
and steering.
--compact Merge consecutive same-category headings in
Markdown output. Markdown-only — a no-op for
HTML.
--git-link TEMPLATE URL template for resolving commit SHAs on
forges not in the built-in map (github.com,
gitlab.com, bitbucket.org). Placeholders:
{host}, {path}, {sha}. Example for self-
hosted GitLab: --git-link
'https://{host}/{path}/-/commit/{sha}'. Can
also be set via the CLAUDE_CODE_LOG_GIT_LINK
env var.
--no-timestamps Suppress per-message timestamp lines in
Markdown output (#160). Markdown-only — a
warning is emitted (but not an error) if
combined with --format html / --format json.
--no-recaps Suppress '※ recap' (away-summary) messages.
Recaps are otherwise shown at every depth
level — they are themselves a high-level
summary of activity (#179). Use this to get
a 'really user-only' view (--depth user
--no-recaps) or to drop the recap/agent
redundancy at --depth assistant.
--theme [classic|minimal|default]
HTML theme: classic (current look), minimal,
or default (the built-in default, currently
classic). Overrides $CLAUDE_CODE_LOG_THEME.
HTML-only. Themes write the same filenames,
so switching theme regenerates every output.
--debug Show full traceback on errors.
--help Show this message and exit.
claude-code-log serve¶
Serve the projects directory over loopback, with full-archive search.
The generated HTML stays canonical and keeps working from file://;
this adds an origin, which is what full-archive search needs in order to
reach the SQLite cache.
Usage:
Options:
--port INTEGER Port to listen on. Use 0 to pick a free one.
[default: 8010]
--projects-dir DIRECTORY Projects directory to serve. Defaults to
~/.claude/projects (the same directory the
conversion uses).
--no-convert Skip the startup conversion and serve
whatever HTML is already there. Faster to
start; pages may be stale.
--open-browser Open the index page in a browser once the
server is up.
--search-fields TEXT Which field groups archive search looks in
by default. Groups: text, thinking,
tool_input, tool_result, attachment, meta.
Accepts an absolute list ('text,thinking'),
'all'/'none', or deltas against the default
('+tool_result', '-thinking'). Default
excludes tool_result: it is 69% of a typical
archive's text and mostly file dumps. Env:
CLAUDE_CODE_LOG_SEARCH_FIELDS.
--index-fields TEXT Which field groups get indexed at all.
Defaults to everything, so enabling a group
at search time never needs a reindex.
Narrowing this shrinks the index (dropping
tool_result took a real 253 MB index to 94
MB) but forces a rebuild. Env:
CLAUDE_CODE_LOG_INDEX_FIELDS.
--reindex Rebuild the search index from scratch
instead of updating it.
--no-index Start without building or updating the
search index. The search page will report
the index as unavailable.
--watch Keep the served pages current: re-convert
whenever a transcript changes, in the
background. Reload a page to see new
messages.
--theme [classic|minimal|default]
HTML theme: classic (current look), minimal,
or default (the built-in default, currently
classic). Overrides $CLAUDE_CODE_LOG_THEME.
HTML-only. Themes write the same filenames,
so switching theme regenerates every output.
--help Show this message and exit.
claude-code-log watch¶
Re-convert transcripts as they change, until interrupted.
Points at one project by default -- the one for the current directory if it has transcripts, otherwise the given INPUT_PATH. Watching the whole archive is available via --all-projects but is rarely what you want: a tick's cost scales with the project, and only one project is ever being written to.
The generated files on disk stay canonical, so anything that reloads them picks the changes up: an editor or Obsidian for Markdown, a browser refresh for HTML.
Usage:
Options:
-o, --output PATH Output destination, as for `convert`. Pair
with --format md to keep an Obsidian vault
current.
-f, --format [html|md|markdown]
Output format. [default: html]
--combined [yes|no|only] As for `convert`, but defaulting to 'no'.
Per-session files are what a watch is for,
and skipping the combined page is what lets
a tick regenerate just the changed session
instead of reloading the whole project.
[default: no]
--projects-dir DIRECTORY Projects directory (default:
~/.claude/projects/).
--all-projects Watch every project instead of one. Off by
default: a tick over a large archive is far
more expensive than over a single project.
--interval FLOAT Seconds between filesystem polls. [default:
0.25]
--quiet-period FLOAT Seconds of no further change before
converting. Claude Code writes several
entries per turn; without this every one
would trigger its own render. [default:
0.3]
--max-latency FLOAT Convert anyway after this long, so an
unbroken stream of appends still surfaces
instead of starving behind the quiet period.
[default: 2.0]
--theme [classic|minimal|default]
HTML theme: classic (current look), minimal,
or default (the built-in default, currently
classic). Overrides $CLAUDE_CODE_LOG_THEME.
HTML-only. Themes write the same filenames,
so switching theme regenerates every output.
--debug Show full tracebacks.
--help Show this message and exit.