API Reference / cli /

trace.py

tuiml trace: view or live-tail MCP tool-call traces.

Every MCP call from an AI client is appended to ~/.tuiml/logs/mcp.jsonl by the running tuiml-mcp server, one JSON record per line: a call record when a tool starts and a return record when it finishes. This command pretty-prints those records and can follow new entries in real time.

Functions

Command

tuiml trace

Line 94
tuiml trace [OPTIONS]

View or follow MCP tool-call traces (live by default, Ctrl-C to stop).

Prints the most recent records from the trace log, then keeps following new ones as connected AI clients call TuiML tools; --no-follow prints the tail and exits instead. Each entry shows the timestamp, the server process id, the tool name, and either its arguments or its result and duration. If the log does not exist yet, the command waits for it rather than failing, so it can be started before the first tool call.

Tracing is on by default and is disabled by setting TUIML_MCP_TRACE=0 for the process that launches the server.

Follow tool calls as they happen:

bash 
$ tuiml trace -f

Print the last 100 records and exit:

bash 
$ tuiml trace --no-follow -n 100

Watch a single tool, as raw JSONL for further processing:

bash 
$ tuiml trace --tool tuiml_train --json

Start a clean log before reproducing a problem:

bash 
$ tuiml trace --clear

Options

-f/-F, --follow/--no-follow
= True
Follow new entries in real time (default: on). --no-follow to print and exit.
-n, --lines
int = 50
Number of recent records to print before following (default: 50).
--tool
Only show records for this tool, e.g. tuiml_train.
--json
flag
Emit the raw JSONL records instead of formatted lines.
--clear
flag
Delete the trace log file and exit without printing.
--path
path
Path to the trace file. Defaults to $TUIML_MCP_TRACE_FILE or ~/.tuiml/logs/mcp.jsonl.