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/logs

Viewing Logs

See the most recent log

crab logs last

This is the fastest way to check what happened during a failed operation.

List all log files

crab logs list

2024-01-14.log
2024-01-15.log
2024-01-16.log

View a specific day's log

crab logs show 2024-01-15.log

Clear all logs

crab logs clear
# cleared /home/user/.crab/logs

Controlling 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

Crab defaults to error, so normal commands do not print internal warning, retry, or fallback logs. Raise the level for one diagnostic run when needed.

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 push

Typical Workflows

Debug a failed push

git push origin main  # fails
crab logs last        # see what happened
crab errors CRAB-E0017  # look up the error code

Attach logs to a bug report

crab logs last > debug-log.txt
crab env > env-info.txt
# Attach both files to your issue

Verbose operation for investigation

CRAB_LOG=debug crab hydrate --all 2> hydrate-debug.log

Capture a bounded diagnostic window

Increase verbosity for one reproducible command instead of leaving trace logs enabled across normal work:

CRAB_LOG='info,crab::storage=debug' crab hydrate models/v2.bin
crab logs last > hydrate-operation.log
crab version --json > crab-version.json

Record the start time, command, exit status, and installed version with the log. Module filters reduce unrelated events and make network retries, cache choices, or storage decisions easier to follow in chronological order. Return to the normal log level after collecting the evidence.

Review before sharing or clearing

Logs avoid credential values by design, but they can contain local paths, repository identities, object keys, provider errors, and user-supplied command arguments. Redact that context according to the incident's sharing boundary.

crab logs clear deletes all managed log files. Export the relevant file and confirm the copy is readable before clearing old logs. Clearing does not fix the underlying command failure; use it only for retention or after evidence has been preserved.

CLI Reference

For complete command syntax and all available flags, see the crab logs reference.