Diagnostics & Repair
Diagnostic Logging
Crab writes structured trace logs for every operation. When something goes wrong, these logs contain the detailed context you need to understand what happened — which chunks were processed, what network calls were made, and where things went sideways.
Log Location
Logs are written to ~/.crab/logs/ by default (one file per day). Override with:
export CRAB_LOG_DIR=/path/to/logsViewing Logs
See the most recent log
crab logs lastThis is the fastest way to check what happened during a failed operation.
List all log files
crab logs list2024-01-14.log
2024-01-15.log
2024-01-16.logView a specific day's log
crab logs show 2024-01-15.logClear all logs
crab logs clear
# cleared /home/user/.crab/logsControlling Verbosity
Set the log level with the CRAB_LOG environment variable or the --log-level flag:
# Environment variable
CRAB_LOG=debug crab add '*.bin'
# CLI flag
crab --log-level debug add '*.bin'Log Levels
| Level | What it captures |
|---|---|
error | User-visible failures only |
warn | Degraded behavior (retries, fallbacks) |
info | Lifecycle events (one per command) |
debug | Operation flow, decisions made |
trace | Per-chunk noise, full request/response details |
Module-Level Filters
Target specific subsystems for detailed logging without flooding the output:
CRAB_LOG=crab::engine=debug crab add '*.bin'
CRAB_LOG=crab::storage=trace crab pushTypical Workflows
Debug a failed push
git push origin main # fails
crab logs last # see what happened
crab errors CRAB-E0017 # look up the error codeAttach logs to a bug report
crab logs last > debug-log.txt
crab env > env-info.txt
# Attach both files to your issueVerbose operation for investigation
CRAB_LOG=debug crab hydrate --all 2> hydrate-debug.logCLI Reference
For complete command syntax and all available flags, see the crab logs reference.