Skip to content

CLI Reference

The chatgpt-to-markdown command-line tool converts ChatGPT data exports into browsable Markdown archives.

Installation

Run without installing (ephemeral environment):

uvx chatgpt-to-markdown --help

Or install as a persistent CLI:

uv tool install chatgpt-to-markdown
chatgpt-to-markdown --help

If you are using a local development checkout, run commands with uv run.

Basic Usage

No-install invocation:

uvx chatgpt-to-markdown <input_dir> <output_dir>

Installed CLI invocation:

chatgpt-to-markdown <input_dir> <output_dir>

Arguments

Argument Required Description
input_dir Yes Path to extracted ChatGPT export directory or ZIP file
output_dir Yes Path to output Markdown archive directory

Options

Option Default Description
--redact-pii / --no-redact-pii True Redact PII (email, phone, birth year) in metadata
--include-thinking False Include thinking/reasoning blocks from o-series models
--deduplicate / --no-deduplicate True Deduplicate assets by SHA-256 hash

Examples

Convert an Extracted Export Directory

uvx chatgpt-to-markdown ./my-export ./archive

Convert a ZIP File Directly

The tool automatically extracts ZIP files to a temporary directory:

uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive

Include Thinking Blocks

For conversations with reasoning models (o-series), include internal thinking:

uvx chatgpt-to-markdown ./my-export ./archive --include-thinking

Disable PII Redaction

Keep email, phone number, and birth year in metadata files:

uvx chatgpt-to-markdown ./my-export ./archive --no-redact-pii

Disable Deduplication

Store duplicate media files separately (larger output):

uvx chatgpt-to-markdown ./my-export ./archive --no-deduplicate

Combine Multiple Options

uvx chatgpt-to-markdown ./chatgpt-export.zip ./archive \
  --no-redact-pii \
  --include-thinking \
  --no-deduplicate

Environment Variables

Override default configuration with environment variables prefixed with CONVERTER_:

Variable Type Default Description
CONVERTER_INPUT_DIR Path ./export Input directory path
CONVERTER_OUTPUT_DIR Path ./archive Output directory path
CONVERTER_REDACT_PII Boolean true Enable PII redaction
CONVERTER_INCLUDE_THINKING Boolean false Include thinking blocks
CONVERTER_DEDUPLICATE_BY_HASH Boolean true Enable SHA-256 deduplication
CONVERTER_MAX_FILENAME_LENGTH Integer 200 Maximum filename length (chars)

Example:

export CONVERTER_REDACT_PII=false
export CONVERTER_INCLUDE_THINKING=true
uvx chatgpt-to-markdown ./my-export ./archive

Exit Codes

Code Meaning
0 Success
1 Error during conversion (check stderr logs)

Common Workflows

First-Time Export

  1. Export your ChatGPT data from Settings → Data controls
  2. Wait for the export email (can take hours)
  3. Download the ZIP file
  4. Run the converter:
uvx chatgpt-to-markdown ~/Downloads/chatgpt-export.zip ~/Documents/chatgpt-archive

Re-Processing an Export

If you want to regenerate the archive with different settings:

# Include thinking blocks this time
uvx chatgpt-to-markdown ./my-export ./archive-with-thinking --include-thinking

# Keep PII for personal archive
uvx chatgpt-to-markdown ./my-export ./archive-full --no-redact-pii

Validate Output

After conversion, review the validation report in stderr:

uvx chatgpt-to-markdown ./my-export ./archive 2>&1 | tee conversion.log

Check for:

  • Missing asset warnings
  • Broken relative links
  • Unresolved file pointers

Next Steps