> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/charmbracelet/crush/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<ParamField path="--follow" type="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`
</ParamField>

<ParamField path="--tail" type="integer" default="1000">
  Show only the last N lines. Default is 1000 lines for performance.

  Short flag: `-t`
</ParamField>

## Global Flags

<ParamField path="--cwd" type="string" default="current directory">
  Current working directory. Used to locate the project's Crush data directory.
</ParamField>

<ParamField path="--data-dir" type="string" default="~/.crush">
  Custom Crush data directory containing the logs.
</ParamField>

Other [global flags](/cli/crush#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

<CodeGroup>
  ```bash View recent logs theme={null}
  # Show last 1000 lines (default)
  crush logs
  ```

  ```bash View last 50 lines theme={null}
  # Show only the last 50 lines
  crush logs --tail 50
  crush logs -t 50
  ```

  ```bash Follow logs theme={null}
  # Follow logs in real-time
  crush logs --follow
  crush logs -f
  ```

  ```bash Follow with custom tail theme={null}
  # Show last 100 lines, then follow
  crush logs --follow --tail 100
  crush logs -f -t 100
  ```

  ```bash Custom data directory theme={null}
  # View logs from a specific project
  crush logs --data-dir /path/to/project/.crush
  ```

  ```bash View logs for current directory theme={null}
  # If in a project directory
  crush logs --cwd .
  ```
</CodeGroup>

## 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)

```json theme={null}
{
  "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

```bash theme={null}
$ 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:

```bash theme={null}
# 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:

```bash theme={null}
# In one terminal, run Crush
crush

# In another terminal, follow logs
crush logs -f
```

### Performance Analysis

Analyze timing and performance:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Logs from today
crush logs | grep "$(date +%Y-%m-%d)"

# Logs from specific hour
crush logs | grep "2025-03-11 14:"
```

### Count Occurrences

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
#!/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

```bash theme={null}
# More verbose logging
crush --debug

# Then view logs
crush logs -f
```

### Environment Variables

Set log level via environment:

```bash theme={null}
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:

```bash theme={null}
# 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`](/cli/stats) - View usage statistics
* [`crush --debug`](/cli/crush#global-flags) - Enable debug logging
* [Logging Guide](/guides/logging) - Complete logging guide
* [Configuration](/configuration/overview) - Configure logging behavior