@escouade/graph-trace-viewer-cli

Open a graph-trace/v1 document in your browser from the terminal. Ships the Vue trace viewer as a pre-built bundle and serves it over a short-lived local HTTP server — no global install of a UI, no manual file juggling.

Install

npm install -g @escouade/graph-trace-viewer-cli

This exposes the gtv command. (Prefer no global install? Use npx @escouade/graph-trace-viewer-cli <file>.)

Usage

Point gtv at any graph-trace/v1 document — typically a file written by @escouade/graph-trace-file-exporter, which saves one .json per run (e.g. ./traces/<traceId>.json):

gtv ./traces/<traceId>.json

The CLI also accepts a .jsonl stream — one { event, span } record per line, as produced by a consumer of the streaming sink (TraceStreamSink). It is folded back into a graph-trace/v1 document with parseTraceJsonl (best-effort: a partial tail — a run without run.end, a truncated last line — is tolerated and the complete runs are kept):

gtv ./traces/<traceId>.jsonl

The CLI:

1. reads the file — a .jsonl extension is folded via parseTraceJsonl, anything else is validated as a graph-trace/v1 document,
2. starts a local HTTP server on 127.0.0.1 (random free port),
3. serves the trace at /trace.json and the viewer at /,
4. opens your default browser at the printed URL.

Graph Trace Viewer running at http://127.0.0.1:43675/
Press Ctrl+C to stop.

Press Ctrl+C to stop the server.

Try the sample traces

The repository ships ready-made documents so you can see the viewer with no setup:

gtv examples/weather-paris.json       # minimal agent → tools loop
gtv examples/research-assistant.json  # planner → draft → 3 parallel critics → finalize

Why a local server (and not file://)?

file:// blocks ES module scripts and breaks relative asset paths (fonts, icons) in modern browsers. A throwaway local HTTP server sidesteps all of it: module scripts load, assets resolve, the viewer fetches the document over fetch('/trace.json'). The server binds to 127.0.0.1 only and lives for the duration of the session.

Peer dependencies

This package renders the viewer at build time, so the published bundle is self-contained. When building from source it relies on:

| Peer | Range | | ----------------------------------- | ------------- | | vue | ^3.5.0 | | primevue | ^4.0.0 | | @escouade/graph-trace-viewer | workspace:^ |

License

MIT — escouade