The crush logs command displays Crush’s application logs, useful for debugging, monitoring, and troubleshooting issues.
Usage Description View the logs generated by Crush. This command provides access to detailed log output including:
Application events
Debug information
Error messages
API calls
Tool executions
Session lifecycle
Logs are formatted with colors and structured fields for easy reading.
Flags Follow log output in real-time. Similar to tail -f, this continuously displays new log entries as they’re written. Short flag: -f
Show only the last N lines. Default is 1000 lines for performance. Short flag: -t
Global Flags --cwd
string
default: "current directory"
Current working directory. Used to locate the project’s Crush data directory.
Custom Crush data directory containing the logs.
Other global flags are also available: --debug
Log File Location Logs are stored at:
Or, if using a custom data directory:
<data-dir>/logs/crush.log
Examples View recent logs
View last 50
Follow logs
Follow with custom tail
Custom data directory
View logs for current directory
# Show last 1000 lines (default) crush logs
Logs are displayed with structured formatting:
Example Log Output 2025-03-11 14:30:45 INFO Session started session_id=abc123 2025-03-11 14:30:46 DEBUG Loading configuration path=/home/user/.crush/crush.json 2025-03-11 14:30:47 INFO Provider initialized provider=anthropic model=claude-sonnet-4-20250514 2025-03-11 14:30:50 DEBUG Tool called tool=read file=/path/to/file.go 2025-03-11 14:30:52 ERROR Failed to execute command error="exit status 1" command=npm install 2025-03-11 14:30:55 WARN Rate limit approaching remaining=5 reset_in=30s
Log Levels Logs are categorized by severity:
DEBUG : Detailed diagnostic informationINFO : General informational messagesWARN : Warning messages (non-critical issues)ERROR : Error messages (failures and exceptions)
Structured Fields Each log entry may include structured fields:
session_id: Unique session identifierprovider: AI provider namemodel: Model being usedtool: Tool namefile: File patherror: Error messagesource: Source code location (file:line)
Logs are stored in JSON format but displayed with human-readable formatting:
Raw JSON (in file) { "time" : "2025-03-11T14:30:45Z" , "level" : "INFO" , "msg" : "Session started" , "session_id" : "abc123" }
2025-03-11 14:30:45 INFO Session started session_id=abc123
Following Logs When using --follow:
Initial display : Shows the last N lines (from --tail)Follow mode : Continuously displays new entriesExit : Press Ctrl+C to stop following
Example Flow $ crush logs -f -t 10 # Shows last 10 lines 2025-03-11 14:30:45 INFO Session started ... # Then displays a separator Showing last 10 lines. Full logs available at: /home/user/.crush/logs/crush.log Following new log entries... # New entries appear in real-time 2025-03-11 14:31:00 INFO New message received 2025-03-11 14:31:05 DEBUG Tool executed successfully ^C # Press Ctrl+C to exit
Use Cases Debugging Issues When something goes wrong:
# View recent errors crush logs --tail 100 | grep ERROR # Follow logs while reproducing issue crush logs --follow
Monitoring Active Sessions Watch what Crush is doing:
# In one terminal, run Crush crush # In another terminal, follow logs crush logs -f
Analyze timing and performance:
# Find slow operations crush logs | grep -i "took\|duration\|time" # Check API response times crush logs | grep -i "response_time"
See which tools are being used:
# Find all tool calls crush logs | grep "Tool called" # Track bash commands crush logs | grep "tool=bash"
Searching Logs Combine with standard Unix tools:
Grep Examples # Find errors crush logs | grep ERROR # Find session-related logs crush logs | grep session_id=abc123 # Case-insensitive search crush logs | grep -i "api key" # Show context around matches crush logs | grep -A 5 -B 5 ERROR
Filter by Time Range # Logs from today crush logs | grep "$( date +%Y-%m-%d)" # Logs from specific hour crush logs | grep "2025-03-11 14:"
Count Occurrences # Count errors crush logs | grep ERROR | wc -l # Count tool calls crush logs | grep "Tool called" | wc -l
Error Messages No Logs Found Looks like you are not in a crush project. No logs found.
Cause : Log file doesn’t exist at the expected location.Solution :# Run Crush to create the log file crush # Or check if you're in the right directory crush logs --data-dir ~/.crush
Failed to Get Flag failed to get <flag-name> flag: <error>
Cause : Internal flag parsing error.Solution : Check your command syntax.Failed to Tail Log File failed to tail log file: <error>
Cause : Permission issue or file is locked.Solution :# Check file permissions ls -lh ~/.crush/logs/crush.log # Try with sudo if needed (not recommended) sudo crush logs
Default Tail Limit The default --tail 1000 limit is for performance:
Prevents loading massive log files into memory
Provides quick startup time
Usually sufficient for debugging
Large Log Files If log files grow very large:
# Check log file size du -h ~/.crush/logs/crush.log # Rotate logs manually mv ~/.crush/logs/crush.log ~/.crush/logs/crush.log.old crush # Creates new log file
When following logs:
Minimal CPU usage in idle state
Near-instant display of new entries
Efficient file watching
Log Rotation Crush doesn’t automatically rotate logs. To manage log files:
Manual Rotation #!/bin/bash # Simple log rotation script LOG_DIR = ~/.crush/logs LOG_FILE = $LOG_DIR /crush.log if [ -f " $LOG_FILE " ]; then TIMESTAMP = $( date +%Y%m%d-%H%M%S ) mv " $LOG_FILE " " $LOG_DIR /crush- $TIMESTAMP .log" gzip " $LOG_DIR /crush- $TIMESTAMP .log" fi
Using Logrotate Create /etc/logrotate.d/crush:
/home/*/.crush/logs/crush.log { daily rotate 7 compress missingok notifempty create 0644 }
Log Verbosity Control log verbosity through:
Debug Mode # More verbose logging crush --debug # Then view logs crush logs -f
Environment Variables Set log level via environment:
export CRUSH_LOG_LEVEL = debug crush
Privacy & Security Logs may contain:
File paths
Command-line arguments
Error messages
API response snippets
Not logged :
API keys (redacted)
Full file contents
Complete API responses
Authentication tokens
Sharing Logs When sharing logs for debugging:
# Redact sensitive information crush logs | sed 's/api_key=.*/api_key=REDACTED/g' > sanitized.log # Or use a specific time range crush logs --tail 100 > debug.log
See Also 