pxForge CLI

AI-powered image editing command-line tool for advanced image processing operations.

Features

• Upload & Manage: Upload images and track them locally
• Resize & Transform: Resize, crop to aspect ratio, and rotate images
• Color Adjustments: Convert to B&W, RGB, adjust contrast and brightness
• AI-Powered Cleanup: Remove backgrounds, objects, and noise
• Advanced Editing: Replace backgrounds, edit with AI prompts, add watermarks

Installation

From Source

cd pxForge
pip install -e .

Development Installation

cd pxForge
pip install -e ".[dev]"

Configuration

By default, pxForge connects to the hosted API at:

https://shlokarora2709-ai-image-editor.hf.space

To use a custom API endpoint, set the environment variable:

export PXFORGE_API_URL="https://your-api-endpoint.com"

Usage

Basic Commands

Upload an Image

pxforge upload path/to/image.jpg

List Uploaded Images

pxforge list

Delete Image ID from Registry

pxforge delete <image-id>

Download Image from URL

pxforge download <url> output/path.jpg

Resize & Transform

Resize Image

pxforge resize <image-id> --width 800 --height 600
pxforge resize <image-id> -w 1920 -h 1080

Crop to Aspect Ratio

pxforge aspect-ratio <image-id> --ratio 16:9
pxforge aspect-ratio <image-id> -r 4:3

Rotate Image

pxforge rotate <image-id> --angle 90
pxforge rotate <image-id> -a 180

Color Adjustments

Convert to Black & White

pxforge to-bw <image-id>

Convert to RGB

pxforge to-rgb <image-id>

Adjust Contrast

pxforge contrast <image-id>

Adjust Brightness

pxforge brightness <image-id>

AI-Powered Cleanup

Remove Background

pxforge remove-bg <image-id>

Remove Object

pxforge remove-object <image-id> --x 100 --y 150 --radius 50

Remove Noise & Enhance

pxforge remove-noise <image-id>

Advanced Editing

Replace Background

pxforge replace-bg <image-id> path/to/new-background.jpg

Edit with AI Prompt

pxforge prompt-edit <image-id> --prompt "make the sky more blue"
pxforge prompt-edit <image-id> -p "add a sunset in the background"

Add Watermark

pxforge watermark <image-id> --text "Copyright 2025" --position bottom-right
pxforge watermark <image-id> -t "My Photo" -p top-left

Watermark positions: top-left, top-right, bottom-left, bottom-right

Command Reference

Getting Help

Commands are organized into 5 categories for easy discovery:

• Basic Commands: upload, list, delete, download
• Resize & Transform: resize, aspect-ratio, rotate
• Color Adjustments: to-bw, to-rgb, contrast, brightness
• AI-Powered Cleanup: remove-bg, remove-object, remove-noise
• Advanced Editing: replace-bg, prompt-edit, watermark

# General help (shows all commands grouped by category)
pxforge --help

# Command-specific help
pxforge upload --help
pxforge resize --help
pxforge prompt-edit --help

Version

pxforge --version

Adding New Commands

1. Create a new function in the appropriate command module
2. Add Click decorators for arguments and options
3. Include comprehensive docstring
4. Register the command in cli.py

Example:

@click.command()
@click.argument("image_id")
@click.option("--param", "-p", help="Parameter description")
def my_command(image_id, param):
    """
    Command description.

    IMAGE_ID: Description of argument
    """
    # Implementation (keep under 30 lines)
    pass

Notes

• AI-powered operations (background removal, noise reduction, prompt editing) may take several minutes
• All processed images are returned as URLs from the cloud storage
• Local registry only stores image IDs, not the actual images
• Network timeouts are set to 10 minutes for heavy AI operations

Troubleshooting

Image ID Not Found

Make sure you've uploaded the image first using pxforge upload and the image ID is in your local registry.

Request Timeout

Some AI operations take time. The CLI automatically handles longer timeouts for heavy operations.