# How to Export earendil pi Sessions to HTML: Complete Guide

> Learn how to export earendil pi sessions to HTML using simple commands or programmatically. Generate syntax-highlighted HTML transcripts easily.

- Repository: [Earendil Works/pi](https://github.com/earendil-works/pi)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Run `pi --export /path/to/file.html` after your REPL session to generate a standalone, syntax-highlighted HTML transcript, or invoke `exportSessionToHtml()` programmatically from the coding-agent package.**

The `earendil-works/pi` repository provides a built-in HTML exporter that transforms JSON session logs into self-contained web pages. Understanding how to export earendil pi sessions to HTML allows you to archive terminal output—including AI conversations, tool results, and ANSI colors—in a portable format suitable for sharing or documentation.

## How the HTML Export Pipeline Works

The export process traverses six distinct stages across the `packages/coding-agent` module. Each component handles a specific transformation from raw session data to final markup.

### CLI Argument Parsing

The entry point resides in [`packages/coding-agent/src/cli/args.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/cli/args.ts), which registers the `--export` flag and captures the target file path. When you append `--export` to your command, the parser validates the path and forwards it to the session manager.

### Session Orchestration

The `AgentSession.exportToHtml` method—implemented around line 2969 in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/agent-session.ts)—serves as the coordinator. It verifies that the session exists on disk (in-memory sessions cannot be exported) and initializes the HTML generation workflow.

### Core HTML Generation

The `ExportHtml` class in [`packages/coding-agent/src/core/export-html/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/export-html/index.ts) walks through the session's message history. It processes metadata, user prompts, assistant replies, and tool outputs, assembling them into a structured document.

### ANSI-to-HTML Conversion

Terminal colors and text styles convert via the parser in [`packages/coding-agent/src/core/export-html/ansi-to-html.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/export-html/ansi-to-html.ts). This module transforms ANSI escape sequences—such as `\x1b[31m` for red text—into safe HTML spans with inline CSS styles.

### Tool Rendering Support

For sessions containing custom tool calls that implement TUI renderers, [`packages/coding-agent/src/core/export-html/tool-renderer.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/export-html/tool-renderer.ts) executes the renderer, captures the ANSI output, and feeds it through the conversion pipeline. If a renderer fails, the system falls back to a generic JSON view rather than aborting the export.

### Template Assembly

The final document injects content into static templates located via `getExportHtmlTemplateDir` in [`packages/coding-agent/src/config.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/config.ts). The resulting file is written atomically and contains no external dependencies.

## Exporting Sessions from the Command Line

To export interactively, first record your session using the TUI, then specify the export path:

```bash

# Launch the interactive REPL

pi

# Quit the REPL, then export the session you just recorded

pi --export ~/reports/session-2024.html

```

The CLI validates that the session file exists before invoking the HTML pipeline. If you attempt to export an unsaved, in-memory session, the tool returns a clear error message instructing you to persist the data first.

## Programmatic HTML Export

For automation scripts or custom workflows, import the export function directly from the source:

```typescript
import { exportSessionToHtml } from "pi/packages/coding-agent/src/core/export-html";

const sessionPath = "/home/user/.pi/session.json";
const outputPath  = "/var/www/docs/session.html";

await exportSessionToHtml(sessionPath, outputPath);
console.log(`Exported to ${outputPath}`);

```

This wrapper loads the JSON session, instantiates the rendering pipeline, and writes the complete HTML document using the bundled templates.

## Rendering Custom Tool Output

Tools that expose a `renderTui` method automatically benefit from rich HTML export. The exporter attempts to execute the renderer and convert the terminal output:

```typescript
// Example tool definition with TUI support
export const MyAnalyzer = {
  name: "analyzer",
  renderTui: (data) => {
    // Returns colored terminal output
    return `\x1b[34mAnalyzing ${data.length} files...\x1b[0m`;
  }
};

```

No additional configuration is required; simply providing the `renderTui` method enables the [`tool-renderer.ts`](https://github.com/earendil-works/pi/blob/main/tool-renderer.ts) module to embed styled output in the final HTML.

## Low-Level ANSI Conversion

If you need to convert raw ANSI strings outside a full session context, use the standalone converter:

```typescript
import { ansiToHtml } from "pi/packages/coding-agent/src/core/export-html/ansi-to-html";

const terminalOutput = "\x1b[32mSuccess\x1b[0m: Build completed";
const htmlFragment = ansiToHtml([terminalOutput]);
// Returns: '<span style="color:#00aa00">Success</span>: Build completed'

```

This utility is useful for debugging or for embedding isolated command output into other documents.

## Summary

- The `--export` flag triggers the pipeline defined in [`packages/coding-agent/src/core/export-html/index.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/export-html/index.ts)
- `AgentSession.exportToHtml` validates that sessions exist on disk before processing
- [`ansi-to-html.ts`](https://github.com/earendil-works/pi/blob/main/ansi-to-html.ts) converts terminal colors into inline CSS while escaping all content to prevent XSS
- Custom tool renderers execute automatically but degrade gracefully to JSON on failure
- Templates are retrieved via `getExportHtmlTemplateDir` in [`packages/coding-agent/src/config.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/config.ts)

## Frequently Asked Questions

### Can I export a session that is still in memory?

No. The exporter requires a persisted JSON session file. If you attempt to export before saving, `AgentSession.exportToHtml` throws an error indicating that only on-disk sessions are supported.

### What happens if a custom tool renderer crashes during export?

The [`tool-renderer.ts`](https://github.com/earendil-works/pi/blob/main/tool-renderer.ts) module wraps renderer execution in a try-catch block. Upon failure, it substitutes a safe JSON representation of the tool output, allowing the remainder of the session to export successfully.

### Is the generated HTML safe to share with untrusted viewers?

Yes. The [`ansi-to-html.ts`](https://github.com/earendil-works/pi/blob/main/ansi-to-html.ts) converter escapes all HTML-sensitive characters before injection, and the templates contain no JavaScript or external resources. The output is a self-contained, static document safe for public distribution.

### Can I customize the appearance of the exported HTML?

Yes. The exporter reads templates from the directory returned by `getExportHtmlTemplateDir` in [`packages/coding-agent/src/config.ts`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/config.ts). Modifying the HTML or CSS files in that directory before running the export allows you to customize styling, fonts, and layout while preserving the content injection logic.