Check Image supports multiple output formats and color modes to suit different use cases, from interactive terminal use to CI/CD pipelines and programmatic parsing.
Check Image supports two output formats controlled by the --output (or -o) flag:
Text (Default) Human-readable output with colors and formatting for terminal use.
JSON Machine-readable JSON for scripting and programmatic parsing.
Text Output Text output is designed for human readability with colored status indicators, structured information, and clear error messages.
Basic text output
Explicit text format
check-image age nginx:latest --max-age 90
Example Output: Checking age of image nginx:latest Image creation date: 2026-02-04T23:53:09Z Image age: 28 days ✓ Image is less than 90 days old Validation succeeded
Checking if image nginx:latest is configured to run as a non-root user ✓ Image runs as non-root user Validation succeeded
Checking if image nginx:latest is configured to run as a non-root user ✗ Image runs as root user Validation failed
Error retrieving the remote image: manifest unknown ✗ Execution error
JSON Output JSON output provides structured data for scripting, automation, and integration with other tools.
Basic JSON output
Pipe to jq
check-image age nginx:latest --max-age 90 --output json check-image size nginx:latest --max-size 100 -o json
Example JSON Output: Age Check
Size Check
All Command
Version
{ "check" : "age" , "image" : "nginx:latest" , "passed" : true , "message" : "Image is less than 90 days old" , "details" : { "created-at" : "2025-12-01T00:00:00Z" , "age-days" : 75 , "max-age" : 90 } }
{ "check" : "size" , "image" : "nginx:latest" , "passed" : true , "message" : "Image size is acceptable" , "details" : { "total-bytes" : 67108864 , "total-mb" : 64.0 , "max-size-mb" : 100 , "layer-count" : 7 , "max-layers" : 20 , "layers" : [ { "index" : 1 , "bytes" : 27155431 }, { "index" : 2 , "bytes" : 25252352 }, { "index" : 3 , "bytes" : 627 } ] } }
{ "image" : "nginx:latest" , "passed" : false , "checks" : [ { "check" : "age" , "image" : "nginx:latest" , "passed" : true , "message" : "Image is less than 90 days old" , "details" : { "created-at" : "2026-02-04T23:53:09Z" , "age-days" : 15.975077092155601 , "max-age" : 90 } }, { "check" : "root-user" , "image" : "nginx:latest" , "passed" : false , "message" : "Image runs as root user" , "details" : { "user" : "" } } ], "summary" : { "total" : 8 , "passed" : 5 , "failed" : 3 , "errored" : 0 , "skipped" : [ "registry" , "labels" ] } }
{ "version" : "v0.19.4" , "commit" : "a1b2c3d" , "built-at" : "2026-02-18T12:34:56Z" , "go-version" : "go1.26.0" , "platform" : "linux/amd64" }
All JSON keys use kebab-case (e.g., age-days, max-size-mb, created-at) for consistency across the tool.
JSON Schema All JSON output follows a consistent schema:
interface CheckResult { check : string ; // Check name (e.g., "age", "size") image : string ; // Image reference passed : boolean ; // Validation result message : string ; // Human-readable message details ?: object ; // Check-specific details error ?: string ; // Error message (if execution failed) }
interface AllResult { image : string ; // Image reference passed : boolean ; // Overall validation result checks : CheckResult []; // Array of individual check results summary : { total : number ; // Total checks attempted passed : number ; // Number of checks passed failed : number ; // Number of checks failed errored : number ; // Number of checks that errored skipped ?: string []; // Names of skipped checks }; }
Color Modes Color output is controlled by the --color flag and only applies to text output.
Color output mode: auto, always, or never.
Auto Mode (Default) Automatically detects whether stdout is a terminal and respects environment variables.
check-image age nginx:latest --color auto
Auto mode behavior:
Terminal Detection
Colors are enabled if stdout is a TTY (interactive terminal).
NO_COLOR Environment Variable
If NO_COLOR is set (any non-empty value), colors are disabled.
CLICOLOR_FORCE Environment Variable
If CLICOLOR_FORCE=1, colors are enabled even in non-TTY environments.
Interactive terminal (colors enabled)
Redirected output (colors disabled)
Piped output (colors disabled)
NO_COLOR set (colors disabled)
CLICOLOR_FORCE set (colors enabled)
check-image age nginx:latest
Always Mode Forces color output regardless of terminal detection.
check-image age nginx:latest --color always
Even with --color always, the NO_COLOR environment variable is still respected for no-color.org compliance. Force colors in pipe
Force colors in redirect
NO_COLOR overrides always
check-image age nginx:latest --color always | less -R
Never Mode Disables color output completely.
check-image age nginx:latest --color never
Plain text output
In CI/CD pipelines
check-image age nginx:latest --color never
Use --color never in CI/CD logs for cleaner, grep-friendly output without ANSI escape codes.
Exit Codes Check Image uses exit codes to indicate the result of validation:
Validation succeeded or no checks ran (skipped).
One or more checks failed validation (image does not meet requirements).
Tool encountered an error and could not complete validation (invalid config, image not found, etc.).
Exit Code Examples Exit 0 (Success)
Exit 1 (Failed)
Exit 2 (Error)
check-image age nginx:latest --max-age 90 echo $? # Output: 0
Image is less than 90 days old → validation succeeded. check-image root-user nginx:latest echo $? # Output: 1
Image runs as root → validation failed. check-image age nonexistent:latest echo $? # Output: 2
Image not found → execution error. Exit Code Precedence In the all command, if multiple checks produce different results, the exit code follows this priority:
Execution Error (Exit 2) - Highest Priority
If any check encounters an execution error, exit code 2 is returned.
Validation Failed (Exit 1)
If one or more checks fail validation but no execution errors occur, exit code 1 is returned.
Validation Succeeded (Exit 0)
If all checks pass, exit code 0 is returned.
Validation Skipped (Exit 0) - Lowest Priority
If no checks ran, exit code 0 is returned.
check-image all nginx:latest --skip registry,labels # 6 checks passed, 2 checks failed, 0 errors → Exit 1 check-image all nginx:latest --registry-policy invalid.json # Some checks passed, some failed, 1 execution error → Exit 2
Using Exit Codes in Scripts Basic error handling
Detailed error handling
CI/CD pipeline
Conditional deployment
if check-image age nginx:latest --max-age 30 ; then echo "Image is fresh" else echo "Image is too old or validation failed" fi
Output Redirection Check Image writes different types of output to different streams:
Text output (validation results)
JSON output
Final status messages (“Validation succeeded”, “Validation failed”)
Log messages (controlled by --log-level)
Error details
Warnings
Redirect output to file
Redirect both stdout and stderr
Separate logs from output
JSON to file, logs to terminal
Silence logs, keep output
check-image age nginx:latest > validation-results.txt
Log Levels Control verbosity of diagnostic logging with the --log-level flag:
Log level: trace, debug, info, warn, error, fatal, panic.
Info level (default)
Debug level (verbose)
Error level (minimal)
check-image age nginx:latest --log-level info
Use --log-level debug when troubleshooting authentication or image retrieval issues.
Best Practices
Use JSON in CI/CD JSON output is ideal for automated parsing, reporting, and integration with other tools. check-image all $IMAGE -o json > results.json jq '.summary' results.json
Use text for terminals Text output with colors provides better readability for interactive use and debugging. check-image age nginx:latest --output text
Disable colors in CI/CD Use --color never in CI/CD logs to avoid ANSI escape codes in log files. check-image all $IMAGE --color never
Check exit codes Always check exit codes in scripts to distinguish between validation failures and execution errors. if ! check-image all $IMAGE ; then echo "Validation failed" exit 1 fi
Commands Explore all available validation commands
Configuration Files Understand policy and configuration file formats
GitHub Action Use Check Image in GitHub Actions workflows
CI/CD Integration Integrate Check Image into your CI/CD pipeline
