Diagnostics & Logging¶
Global flags, adopted from sq, control verbose output, file logging, error
rendering, and profiling.
They are cross-cutting concerns handled at the CLI boundary. They never change query results.
Flags¶
| flag | default | effect |
|---|---|---|
-v, --verbose |
off | print diagnostics (source resolved, store opened, query complete with scan count and elapsed) to stderr, plus the query plan and a live backend command trace (disables the progress spinner) |
--log |
off | enable logging to a file (also via IQ_LOG) |
--log.file |
<user cache dir>/iq/iq.log |
log file path. An empty value disables logging |
--log.level |
DEBUG |
DEBUG, INFO, WARN, or ERROR |
--log.format |
text |
text or json |
--error.format |
text |
error output format: text or json |
--error.stack |
off | print the wrapped error cause chain to stderr (can include backend internals, credentials stay redacted) |
--no-progress |
off | disable the scan progress spinner (-v disables it too). See Global flags |
--error.format.text.verbose |
on | for a jq syntax error in text format, draw a caret span under the offending token |
--debug.pprof |
off | write a runtime profile of the whole run: cpu, mem, block, mutex, goroutine, thread, or trace |
marks a flag every iq command accepts (see Global flags).
Logging
The --log* flags also read the environment when the flag is not set. The
precedence is flag > env > default. The environment variables are
IQ_LOG, IQ_LOG_FILE, IQ_LOG_LEVEL, IQ_LOG_FORMAT.
--log writes structured records to a file (down to the chosen level,
always plain, never tinted). A source location is always redacted before
it is logged, so a stored credential never reaches a log file.
Verbose
-v writes a terse human stream to stderr (INFO and above). The stream is
tinted when stderr is a terminal. It follows the same -M/-C/NO_COLOR
decision as colored output.