watchtower tail
Run a Python script and stream events in real-time
Usage
watchtower tail <script...>
Arguments
| Argument | Description |
|---|---|
| script | Command and arguments to run |
Examples
# Basic usage watchtower tail python my_agent.py # With script arguments (use -- to separate) watchtower tail -- python my_agent.py --verbose # With multiple arguments watchtower tail -- python my_agent.py --config prod.yaml --user alice
Environment Variables
The CLI automatically sets these environment variables for the spawned process:
| Variable | Value | Purpose |
|---|---|---|
| PYTHONUNBUFFERED | 1 | Disable Python output buffering |
| WATCHTOWER_LIVE | 1 | Signal SDK to enable stdout streaming |
| WATCHTOWER_RUN_ID | <uuid> | Unique run identifier |
Interface
┌─────────────────────────────────────────────────────────────┐
│ watchtower • LIVE • Run: xyz789 ● REC │
├─────────────────────────────────────────────────────────────┤
│ Stats │
│ Duration: 1.2s LLM: 1 Tools: 2 Tokens: 847 Errors: 0 │
├─────────────────────────────────────────────────────────────┤
│ Events 4 events│
│ +0ms ▶ run.start research_agent │
│ +12ms → llm.request gemini-2.0-flash │
│ +847ms ← llm.response 847 tokens 835ms │
│ +850ms ⚙ tool.start search_web │
│ │
│ Waiting for events... │
├─────────────────────────────────────────────────────────────┤
│ Ctrl+C Stop p Pause q Quit │
└─────────────────────────────────────────────────────────────┘
SDK Integration
Your Python script must enable stdout streaming to work with tail:
import os
from watchtower import AgentTracePlugin
plugin = AgentTracePlugin(
enable_stdout=os.environ.get("WATCHTOWER_LIVE") == "1",
run_id=os.environ.get("WATCHTOWER_RUN_ID"),
)Keyboard Shortcuts
| Key | Action |
|---|---|
| p | Pause / Resume streaming |
| Ctrl+C | Stop the running process |
| q | Quit |