bolens/image-utils

image-utils

Convert raster formats, prepare previews, inspect metadata, and check image libraries from the command line. Your originals stay where they are.

Browse the site · Documentation · Command catalog · Architecture diagram

Start here

GNU/Linux, Bash 4.3+, and Python 3.11+. See requirements for operation-specific dependencies.

git clone https://github.com/bolens/image-utils.git
cd image-utils
bin/image-utils list
bin/image-utils image-thumbnail --size 640x640 --output-dir ./previews ./originals
# Review the plan, then add --apply to create outputs.

38 commands cover conversion, inspection, and library maintenance. Tool directories are thin Bash entry points over a shared Python engine, following the layout and preservation intent of audio-utils.

Working contract

• Writes require --apply. --dry-run suppresses writes, including report files.
• Sources are retained. Outputs are verified in a temporary directory and published without overwriting existing destinations.
• Inputs can be files or recursive directory trees. Input symlinks are not followed. Filenames travel as arguments, never shell code.
• JSON results go to stdout. Progress and failures go to stderr. Exit codes are 0 success, 1 operation failure, 2 usage or dependency failure.
• -j 1..32 controls batch concurrency. --output-dir preserves relative paths and appends the output suffix to the complete source name.
• The stdio MCP server exposes only read-only tools under explicitly allowed roots.

Development

make check
make test
make test-functional
make test-all
make generate
make install-hooks
make -C util/transform/image-thumbnail help

Docker · CLI and configuration · Formats and limits · Architecture · MCP · Tests · Release procedure · Contributing

Status

Initial 0.1.0 implementation. This is a sibling suite, not a claim of identical feature maturity or codec coverage to audio-utils. The parity notes explain the implemented conventions and deliberate differences.

MIT license. External encoders keep their own licenses.

License scope and attribution

See third-party notices for the project license scope, retained upstream notices, and dependency or asset exceptions.