- Go 53.9%
- TypeScript 20.8%
- JavaScript 9.5%
- CSS 8.2%
- HTML 7.1%
- Other 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| frontend | ||
| .gitignore | ||
| app.go | ||
| bugstofix.txt | ||
| build.sh | ||
| config.go | ||
| config_test.go | ||
| global.go | ||
| go.mod | ||
| imageprocessor.go | ||
| imageprocessor_test.go | ||
| LICENSE | ||
| main_cli.go | ||
| main_gui.go | ||
| README.md | ||
| wails.json | ||
| watermark.go | ||
| watermark_test.go | ||
Watermarker
A fast Go tool for batch-watermarking images, available as a CLI and as a desktop GUI (via Wails).
Point it at a folder or a file, give it a watermark image, and it stamps every JPEG/PNG it finds with a resized, positioned, opacity-adjusted copy of that watermark — writing output atomically so a crash mid-run never leaves a corrupt file behind.
Features
- Batch-processes a single image, a directory, or several paths at once
- Optional recursive processing of subdirectories
- Watermark size, opacity, position (anchor + pixel offsets) are all configurable
- Per-run JPEG quality control, with automatic lossless PNG output at quality 100
- Persistent YAML config so you don't have to repeat flags every run (addition of other file formats plausible in the future but not a priority at the moment)
- Safe by default: won't overwrite existing files unless
--overwriteis passed - Multiple configurations can be saved side by side
- Optional GUI built with Wails, sharing the same core image-processing code as the CLI
Building
Requires Go 1.26+.
./build.sh
This formats the code, builds the CLI (watermarker-cli), and installs it to ~/.local/bin/. If the Wails CLI is installed, it also builds the GUI (watermarker-gui) and installs it alongside. It's a thin convenience wrapper, not a build spec — see below for what it's actually doing and how to do it yourself.
Building the CLI manually
main_cli.go carries the //go:build !gui constraint and main_gui.go/app.go carry //go:build gui, so a plain build with no tags compiles only the CLI entry point:
go build -o watermarker-cli .
Cross-compiling works the normal Go way, e.g. for a Linux ARM64 target from any host:
GOOS=linux GOARCH=arm64 go build -o watermarker-cli .
Building the GUI manually
The GUI needs the gui build tag (to pull in main_gui.go/app.go instead of main_cli.go) plus a webkit tag that must match the WebKitGTK dev package installed on the build machine:
webkit2_41— WebKitGTK 4.1, present on newer distros (Debian 13, Ubuntu 24.04+, current Arch/Fedora). This is whatbuild.shuses.- omit it entirely — WebKitGTK 4.0, for older distros that don't ship the 4.1 dev package.
A raw go build with the gui tag will compile and type-check the Go side, but it won't regenerate JS/TS bindings or bundle the frontend — it's only useful as a quick compile check:
go build -tags "gui webkit2_41" .
For an actual runnable GUI binary, use the Wails CLI, which additionally runs wails generate module and the frontend's npm run build before compiling Go:
wails build -tags "gui webkit2_41"
Drop webkit2_41 from that command on older distros. For live-reload development instead of a production build:
wails dev -tags "gui webkit2_41"
Usage
watermarker-cli [flags] [path...]
If no path is given, the current working directory is used. Each path can be a single image or a directory (directories are scanned for .png/.jpg/.jpeg files).
Examples
Watermark every image in the current directory, writing output next to the originals with a _wm suffix:
watermarker-cli --wmpath="logo.png"
Watermark a whole photo library recursively, sending output to a separate folder:
watermarker-cli --wmpath="logo.png" --recursive --outputdir="/tmp/watermarked"
Overwrite images in place (prompts for confirmation unless -y is passed):
watermarker-cli --wmpath="logo.png" --overwrite -y
Save the current flags as your default configuration:
watermarker-cli --wmpath="logo.png" --wmsizeratio=15 --wmanchor=bottomRight --saveconfig
Flags
| Flag | Description | Default |
|---|---|---|
-c, --configuration |
Configuration to be used on this run | — |
-o, --outputdir |
Output folder for the processed images | /tmp |
--openoutput |
Open output folder upon completion | true |
--outputsuffix |
Suffix appended to output filenames | _wm |
-r, --recursive |
Also process subdirectories | false |
--overwrite |
Overwrite existing files in the output location | false |
--hidden |
Also process hidden files/directories (dotfiles) | false |
--quality |
JPEG quality (1–100); 100 forces lossless PNG output |
92 |
--wmpath |
Path to the watermark image | — |
--wmsizeratio |
Watermark size as a percentage of the target image's largest dimension | 12 |
--wmopacity |
Watermark opacity, 0 (invisible) to 1 (full) |
1 |
--wmxoffset |
Watermark horizontal offset (% of image width) | 4 |
--wmyoffset |
Watermark vertical offset (% of image width) | 4 |
--wmanchor |
Anchor position: combine top/bottom/middle with Left/Right/Center, e.g. bottomRight |
bottomRight |
-y |
Skip confirmation prompts | false |
--verbose |
Verbose (debug) logging | false |
--saveconfig |
Save the current flag values to the config file | false |
--displayconfig |
Print the current configuration and exit | false |
Run watermarker-cli --help for the full, up-to-date list.
Configuration file
Settings persist in a YAML file at $XDG_CONFIG_HOME/watermarker/default.yaml (or ~/.config/watermarker/default.yaml if XDG_CONFIG_HOME is unset). It's created automatically on first run with sane defaults, and updated whenever --saveconfig is passed. Command-line flags always take precedence over the config file for the current run.
GUI
The GUI shares the config and watermarking logic with the CLI, built as a desktop app with Wails. Install the Wails CLI first, then see Building the GUI manually above for the exact build/dev commands and build tags.
The frontend source lives in frontend/.
Project layout
main_cli.go— CLI entry point and flag definitions (build tag: notgui)main_gui.go,app.go— Wails GUI entry point and bound app methods (build tag:gui)watermark.go— watermark resizing, opacity, and positioning logicimageprocessor.go— image I/O, directory walking, and atomic file writesconfig.go— YAML config loading/saving via Viperglobal.go— shared flags, globals, and loggersfrontend/— GUI frontend source
License
Licensed under the GNU General Public License v3.0 or later. See LICENSE for the full text.