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.
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); '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 × the largest stale project.
[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.
--debug Show full traceback on errors.
--help Show this message and exit.