Implementation:Guardrails ai Guardrails CLI Watch

Knowledge Sources	Guardrails
Domains	CLI, Tracing, Monitoring
Last Updated	2026-02-14 00:00 GMT

Overview

The watch CLI command provides a real-time tail-like view of guard execution trace logs, with support for plain and rich-formatted output.

Description

This module implements the guardrails watch CLI command using the Typer framework. The command reads guard trace logs from the SQLite trace database and displays them in the terminal. It supports:

• Rich formatting (default): Uses the rich library to display log entries with formatted output.
• Plain mode: Outputs each log entry as a JSON string on a single line, suitable for piping to other tools.
• Follow mode (default enabled): Continuously polls the database for new entries, similar to tail -f.
• History display: The --num-lines option limits output to the most recent N entries.
• Log clearing: The --clear flag deletes all log entries and exits.

The command uses TraceHandler to obtain a reader for the log database and waits for the log file to become available if it does not yet exist.

Usage

Use the watch command to monitor guard executions in real time during development and debugging. It is analogous to tail -f for guard trace logs.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/cli/watch.py
• Lines: 1-77

Signature

@gr_cli.command(name="watch")
def watch_command(
    plain: bool = typer.Option(default=False, is_flag=True, help="..."),
    num_lines: int = typer.Option(default=0, help="..."),
    follow: bool = typer.Option(default=True, help="..."),
    clear: bool = typer.Option(default=False, is_flag=True, help="..."),
):

def _wait_for_logfile():
def _print_fancy(log_msg: GuardTraceEntry):
def _print_and_format_plain(log_msg: GuardTraceEntry) -> None:
def _clear_and_quit():

Import

from guardrails.cli.watch import watch_command

I/O Contract

watch_command CLI Options

Option	Type	Default	Description
--plain	bool (flag)	False	Disable rich formatting; print each entry as a JSON line.
--num-lines	int	0	Show only the last N entries. 0 shows all history.
--follow	bool	True	Continuously watch for new log entries.
--clear	bool (flag)	False	Clear all log entries and exit immediately.

Helper Functions

Function	Description
_wait_for_logfile()	Polls until the log database file exists and is readable. Returns a TraceHandler reader.
_print_fancy(log_msg)	Renders a GuardTraceEntry using rich.print for formatted terminal output.
_print_and_format_plain(log_msg)	Converts a GuardTraceEntry to JSON and prints as a single line.
_clear_and_quit()	Creates a TraceHandler writer, clears all logs, and exits the process via sys.exit(0).

Usage Examples

# CLI usage (from terminal):

# Watch all guard logs with rich formatting (default)
# guardrails watch

# Watch in plain JSON mode
# guardrails watch --plain

# Show only the last 10 entries, then follow
# guardrails watch --num-lines 10

# Show all history without following
# guardrails watch --no-follow

# Clear all guard logs
# guardrails watch --clear

Related Pages

• Guardrails_ai_Guardrails_TraceHandler - The singleton trace handler used to access the log database
• Guardrails_ai_Guardrails_SQLiteTraceHandler - The underlying SQLite storage for trace logs
• Guardrails_ai_Guardrails_CLI_Validate - The companion CLI command for validating LLM outputs