GIMP CLI
A stateful command-line interface for image editing, built on Pillow. Designed for AI agents and power users who need to create and manipulate images without a GUI.
Prerequisites
- Python 3.10+
Pillow(image processing)click(CLI framework)numpy(blend modes, pixel analysis)
Optional (for interactive REPL):
prompt_toolkit
Install Dependencies
pip install Pillow click numpy prompt_toolkit
How to Run
All commands are run from the agent-harness/ directory.
One-shot commands
# Show help
python3 -m cli.gimp_cli --help
# Create a new project
python3 -m cli.gimp_cli project new --width 1920 --height 1080 -o my_project.json
# Create with a profile
python3 -m cli.gimp_cli project new --profile hd720p -o project.json
# Open a project and show info
python3 -m cli.gimp_cli --project project.json project info
# JSON output (for agent consumption)
python3 -m cli.gimp_cli --json --project project.json project info
Interactive REPL
python3 -m cli.gimp_cli repl
python3 -m cli.gimp_cli repl --project my_project.json
Inside the REPL, type help for all available commands.
Command Reference
Project
project new [--width W] [--height H] [--mode RGB|RGBA|L|LA] [--profile P] [-o path]
project open <path>
project save [path]
project info
project profiles
project json
Available profiles: hd1080p, hd720p, 4k, square1080, a4_300dpi, a4_150dpi,
letter_300dpi, web_banner, instagram_post, instagram_story, twitter_header,
youtube_thumb, icon_256, icon_512
Layer
layer new [--name N] [--type image|text|solid] [--fill F] [--opacity O] [--mode M]
layer add-from-file <path> [--name N] [--position P] [--opacity O] [--mode M]
layer list
layer remove <index>
layer duplicate <index>
layer move <index> --to <position>
layer set <index> <property> <value>
layer flatten
layer merge-down <index>
Layer properties: name, opacity (0.0-1.0), visible (true/false),
mode (blend mode), offset_x, offset_y
Canvas
canvas info
canvas resize --width W --height H [--anchor center|top-left|...]
canvas scale --width W --height H [--resample lanczos|bicubic|bilinear|nearest]
canvas crop --left L --top T --right R --bottom B
canvas mode <RGB|RGBA|L|LA|CMYK|P>
canvas dpi <value>
Filters
filter list-available [--category adjustment|blur|stylize|transform]
filter info <name>
filter add <name> [--layer L] [--param key=value ...]
filter remove <index> [--layer L]
filter set <index> <param> <value> [--layer L]
filter list [--layer L]
Available filters:
- Adjustments: brightness, contrast, saturation, sharpness, autocontrast, equalize, invert, posterize, solarize, grayscale, sepia
- Blur: gaussian_blur, box_blur, unsharp_mask, smooth
- Stylize: find_edges, emboss, contour, detail
- Transform: rotate, flip_h, flip_v, resize, crop
Media
media probe <file>
media list
media check
media histogram <file>
Export
export presets
export preset-info <name>
export render <output> [--preset name] [--overwrite] [--quality Q] [--format F]
Available presets: png, png-max, jpeg-high, jpeg-medium, jpeg-low,
webp, webp-lossless, tiff, tiff-none, bmp, gif, pdf, ico
Draw
draw text --layer L --text "Hello" [--x X] [--y Y] [--font F] [--size S] [--color C]
draw rect --layer L --x1 X --y1 Y --x2 X --y2 Y [--fill C] [--outline C]
Session
session status
session undo
session redo
session history
JSON Mode
Add --json before the subcommand for machine-readable output:
python3 -m cli.gimp_cli --json --project p.json layer list
Running Tests
cd agent-harness
python3 -m pytest cli/tests/test_core.py -v # Unit tests (no images needed)
python3 -m pytest cli/tests/test_full_e2e.py -v # E2E tests (creates test images)
python3 -m pytest cli/tests/ -v # All tests
Example Workflow
# Create a project
python3 -m cli.gimp_cli project new --width 1920 --height 1080 --profile hd1080p -o edit.json
# Add an image layer
python3 -m cli.gimp_cli --project edit.json layer add-from-file photo.jpg --name "Background"
# Apply filters
python3 -m cli.gimp_cli --project edit.json filter add brightness --layer 0 --param factor=1.2
python3 -m cli.gimp_cli --project edit.json filter add contrast --layer 0 --param factor=1.1
python3 -m cli.gimp_cli --project edit.json filter add saturation --layer 0 --param factor=1.3
# Add a text overlay
python3 -m cli.gimp_cli --project edit.json layer new --type text --name "Title"
python3 -m cli.gimp_cli --project edit.json draw text --layer 0 --text "My Photo" --size 48 --color "#ffffff"
# View the layer stack
python3 -m cli.gimp_cli --project edit.json layer list
# Save and render
python3 -m cli.gimp_cli --project edit.json project save
python3 -m cli.gimp_cli --project edit.json export render output.jpg --preset jpeg-high --overwrite
Blend Modes
Supported blend modes for layer compositing:
normal, multiply, screen, overlay, soft_light, hard_light,
difference, darken, lighten, color_dodge, color_burn,
addition, subtract, grain_merge, grain_extract
Metadata
Release files for cli-anything-gimp 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cli_anything_gimp-1.0.0.tar.gz | 42.7 kB | Without provenance | Details for cli_anything_gimp-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cli_anything_gimp-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for cli_anything_gimp-1.0.0-py3-none-any.whl |
Total release size: 91.9 kB
Release files / cli_anything_gimp-1.0.0.tar.gz
| Download URL | cli_anything_gimp-1.0.0.tar.gz |
|---|---|
| Size | 42.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f898e1d3742bdc4d5fe5f6231073ea3a40c97cfffdb35e401723e96c84c26efe
|
|
BLAKE2b-256 checksum How to use checksums |
0e11baaef8ff010c0a9315136d6e1b2deb6b5d8acb912bf6645c701999ded80b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / cli_anything_gimp-1.0.0-py3-none-any.whl
| Download URL | cli_anything_gimp-1.0.0-py3-none-any.whl |
|---|---|
| Size | 49.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
366a0d536314aaf59cad954006c9a1b8b5395c9cfb23655ef285e70dee813248
|
|
BLAKE2b-256 checksum How to use checksums |
2cefec5ea5d86a888fe5070b20a71940053d1f278335d8092c8af6fa6307d6b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for cli-anything-gimp 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.