imgmod

Image modification helpers.

• https://remino.net/imgmod/
• Source code

2026 Rémino Rem https://remino.net/

• Installation
  • Homebrew
  • Download
  • Git clone
• Usage
  • Completions
    • Bash
    • Zsh
    • Fish
  • Chains
  • collage
  • New Plugins
  • Plugins
  • Plugin Hooks
  • Optim
  • png8
  • scale4x
  • socshare
  • vidframe

Installation

Homebrew

brew install remino/remino/imgmod
imgmod

Download

Go to the GitHub download page for the latest release, and download the source code from there.

Git clone

git clone git@github.com:remino/remutils.git
cd remutils/imgmod
./imgmod

Usage

Run imgmod without arguments to see how to use it.

Use -O, --optim, or --optimize before a command to optimize image outputs reported by that command with image_optim:

imgmod -O socshare image.png
imgmod --optim socshare image.png
imgmod --optimize socshare image.png

-O optimizes the outputs of a normal command. Command plugins use -o for explicit output paths. Top-level -o still works as a deprecated alias for -O.

Plugins report optimizable image output with the shared hook:

imgmod_output "$file"

Only files reported through this hook are optimized.

When an output path already exists, imgmod prompts before overwriting it on a TTY. Use -y or --overwrite before the command to overwrite without prompting, -i or --interactive to always prompt, or -N or --no-overwrite to refuse overwrites.

Completions

Homebrew installs Bash, Zsh, and Fish completion files automatically. If your shell is already configured to load Homebrew completions, restart the shell and completion should work:

imgmod <Tab>
imgmod help <Tab>
imgmod socshare -<Tab>

For manual setup, add the command for your shell to its startup file.

Bash

source <(imgmod completion bash)

Add that line to ~/.bashrc or ~/.bash_profile to load it in new shells.

Zsh

eval "$(imgmod completion zsh)"

Add that line to ~/.zshrc to load it in new shells.

Fish

imgmod completion fish | source

Add that line to ~/.config/fish/config.fish to load it in new shells.

Completions include bundled commands and executable plugins found in XDG plugin directories. Completion candidates come from the bundled completion plugin:

imgmod completion commands

The generated shell scripts can also be inspected directly:

imgmod completion bash
imgmod completion zsh
imgmod completion fish

Chains

Run multiple plugins in sequence with chain. Separate each plugin stage with --, then pass the input and final output after the last separator:

imgmod chain socshare -f png -- socshare -f webp -- image.png output.webp

Chainable plugins must accept the standard plugin arguments:

<command> [<options>] [-o <output>] <input>

The final output path is required for chains.

collage

Stitch multiple images together vertically or horizontally:

imgmod collage input-a.png input-b.png
imgmod collage -H -o output.png images/

Use -V for vertical collages, which is the default. Vertical collages scale images down to the smallest input width before stitching. Use -H for horizontal collages, which scale images down to the smallest input height.

Inputs can be files or directories. Directories are searched recursively. When -o is omitted, the output path is generated from the first discovered input file with a -collage suffix.

Optim

Optimize an image directly with image_optim:

imgmod optim image.png
imgmod optim -o output.png image.png

When no output is provided, the input is optimized in place. The top-level -O flag, also available as --optim or --optimize, optimizes a normal command's reported outputs:

imgmod -O socshare image.png

png8

Convert an image to PNG8:

imgmod png8 input.png
imgmod png8 -o output.png input.png

When output is omitted, the output path is generated with a -png8.png suffix.

scale4x

Scale an image 4x without antialiasing or smoothing:

imgmod scale4x input.png
imgmod scale4x -o output.png input.png

When output is omitted, the output path is generated with a -4x suffix and the input extension.

watermark

imgmod watermark -w <watermark> [-o <output>] <input>

Apply an image watermark. The watermark is sized relative to the longest input dimension and placed at the lower left by default:

imgmod watermark -w logo.png -o photo-watermarked.jpg photo.jpg

addwatermark remains available as a compatibility wrapper for its former <watermark> <input> <output> argument order.

New Plugins

Create a plugin in your XDG data directory:

imgmod newplugin watermark
# ~/.local/share/imgmod/plugins/imgmod-watermark

Create a plugin at an exact relative or absolute path:

imgmod newplugin ./watermark
imgmod newplugin /absolute/path/watermark

Use a custom Mustache template:

imgmod newplugin -t ./plugin.mustache watermark

imgmod -n watermark is a shortcut for imgmod newplugin watermark.

Existing files are not overwritten.

Plugins

imgmod commands are executable plugin files named imgmod-<command>. Bundled plugins are installed next to the imgmod wrapper, and local plugins can be added under XDG data directories:

~/.local/share/imgmod/plugins/imgmod-watermark

Run a plugin by name:

imgmod watermark image.png

That command resolves to an executable named imgmod-watermark. Plugins that use the shared runtime support -v and --version:

imgmod watermark -v

Plugin lookup order allows local commands to override bundled commands:

1. $XDG_DATA_HOME/imgmod/plugins, defaulting to $HOME/.local/share/imgmod/plugins.
2. Each $XDG_DATA_DIRS entry with /imgmod/plugins appended, defaulting to /usr/local/share/imgmod/plugins and /usr/share/imgmod/plugins.
3. Bundled plugins next to the imgmod script.

Bundled plugins source lib/imgmod.sh for common helpers. Local plugins can source that library too, or remain standalone if they do not need shared helpers.

Plugin Hooks

Plugins that use lib/imgmod.sh should define hooks using the normalized plugin prefix and call imgmod_plugin_run "$@" at the end:

watermark_start() {
    imgmod_output "$file"
}

imgmod_plugin_run "$@"

For a plugin named watermark, PLUGIN_PREFIX is watermark. For a plugin named socshare, PLUGIN_PREFIX is socshare. Define <prefix>_help to show plugin-specific usage. The shared runtime handles -v and --version automatically. Use imgmod_output "$file" for image files that can be optimized with imgmod -O.

socshare

imgmod socshare [-f <format>] [-o <output>] <input>

Crop and resize an image to 1200x630 for Open Graph and Twitter cards.

When output is omitted, the output path is generated from the input path:

imgmod socshare image.png
# image-pubshare.jpg

Use -f to select a different output format:

imgmod socshare -f png image.png
# image-pubshare.png

vidframe

Extract one frame from a video:

imgmod vidframe export.mov
imgmod vidframe -t 00:00:02.500 -o still.png export.mov
imgmod vidframe -f 12 -o frame-12.png export.mov

When no frame or timestamp is specified, the first frame is extracted. -f uses a zero-based frame number, and -t accepts an ffmpeg timestamp.