RalphTUI

logs

View and manage iteration output logs from Ralph TUI sessions.

Synopsis

Bash
ralph-tui logs [options]

The logs command lets you view, filter, and manage the output logs from Ralph's iterations. Each iteration's agent output is saved to a log file, making it easy to review what happened during execution.

INFO

Log files are stored in .ralph-tui/iterations/ by default. Use the --output-dir flag on run to change this location.

Options

Viewing Options

OptionDescription
--iteration <n>View specific iteration number
--task <id>View logs for a specific task ID
--verboseShow full output (not truncated)

Cleanup Options

OptionDescription
--cleanClean up old log files
--keep <n>Number of recent logs to keep (with --clean)
--dry-runPreview cleanup without deleting

Examples

View Specific Iteration

Bash
# View iteration 5
ralph-tui logs --iteration 5
 
# View with full output (no truncation)
ralph-tui logs --iteration 5 --verbose

View Logs for a Task

Bash
# Find all iterations that worked on a specific task
ralph-tui logs --task US-005

List All Logs

Bash
# View summary of all iterations
ralph-tui logs

Example output:

Iteration Logs (.ralph-tui/iterations/)
═══════════════════════════════════════

#  Iteration  Task       Status     Duration   Size
─  ─────────  ─────────  ─────────  ─────────  ─────
1  iter-001   US-001     complete   2m 34s     12KB
2  iter-002   US-002     complete   1m 45s     8KB
3  iter-003   US-003     complete   3m 12s     15KB
4  iter-004   US-004     failed     4m 01s     22KB
5  iter-005   US-004     complete   2m 18s     11KB

Total: 5 iterations, 4 completed, 1 failed

Clean Up Old Logs

Bash
# Preview what would be deleted
ralph-tui logs --clean --dry-run
 
# Keep only the 10 most recent logs
ralph-tui logs --clean --keep 10
 
# Delete all but the last 5
ralph-tui logs --clean --keep 5
INFO

The --clean operation permanently deletes log files. Use --dry-run first to preview what will be removed.

Log File Format

Each iteration creates a log file with the following naming pattern:

.ralph-tui/iterations/
├── iter-001-US-001-2024-01-15T10-30-00.log
├── iter-002-US-002-2024-01-15T10-35-00.log
└── iter-003-US-003-2024-01-15T10-42-00.log

The log files contain:

  • Timestamp - When the iteration started
  • Task details - ID, title, and description
  • Prompt sent - The full prompt built from the template
  • Agent output - Complete stdout/stderr from the agent
  • Completion status - Whether <promise>COMPLETE</promise> was detected
  • Duration - How long the iteration took

Debugging Failed Tasks

When a task fails, the logs are essential for debugging:

Find the Failed Iteration

Bash
ralph-tui logs

Look for iterations with "failed" status.

View Full Output

Bash
ralph-tui logs --iteration 4 --verbose

Review the complete agent output for error messages.

Check the Prompt

The log includes the prompt that was sent. Verify it contains the expected task details and context.

Fix and Retry

Address the issue (fix code, update task, adjust prompt template) and resume execution.

Storage Considerations

Logs can accumulate over time, especially with verbose agent output:

Bash
# Check total log size
du -sh .ralph-tui/iterations/
 
# Clean up periodically
ralph-tui logs --clean --keep 20
INFO

Consider adding .ralph-tui/iterations/ to your .gitignore to avoid committing large log files.

Related Commands

  • run - Start execution (use --output-dir to customize log location)
  • status - Check current session status
  • resume - Continue from where you left off