crush logs

View and follow Crush application logs

The crush logs command displays Crush’s application logs, useful for debugging, monitoring, and troubleshooting issues.

Usage

crush logs [flags]

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 · boolean · default: "false"

Follow log output in real-time. Similar to tail -f, this continuously displays new log entries as they’re written.

Short flag: -f

--tail · integer · default: "1000"

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.

--data-dir · string · default: "~/.crush"

Custom Crush data directory containing the logs.

Other global flags are also available: --debug

Log File Location

Logs are stored at:

~/.crush/logs/crush.log

Or, if using a custom data directory:

<data-dir>/logs/crush.log

Examples

View recent logs

# Show last 1000 lines (default)
crush logs

Output Format

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 information
• INFO: General informational messages
• WARN: Warning messages (non-critical issues)
• ERROR: Error messages (failures and exceptions)

Structured Fields

Each log entry may include structured fields:

• session_id: Unique session identifier
• provider: AI provider name
• model: Model being used
• tool: Tool name
• file: File path
• error: Error message
• source: Source code location (file:line)

Log Format

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"
}

Formatted Display

2025-03-11 14:30:45 INFO  Session started session_id=abc123

Following Logs

When using --follow:

1. Initial display: Shows the last N lines (from --tail)
2. Follow mode: Continuously displays new entries
3. Exit: 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

Performance Analysis

Analyze timing and performance:

# Find slow operations
crush logs | grep -i "took\|duration\|time"

# Check API response times
crush logs | grep -i "response_time"

Tool Execution Tracking

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

Performance Considerations

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

Following Performance

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

Sensitive Information

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

• crush stats - View usage statistics
• crush --debug - Enable debug logging
• Logging Guide - Complete logging guide
• Configuration - Configure logging behavior