Command Line Tools
GUI Image Studio provides powerful command-line tools for automation, batch processing, and integration with build systems. This guide covers all available CLI commands and their usage patterns.
Overview of CLI Tools
GUI Image Studio includes three main command-line tools:
gui-image-studio-designer: Launch the visual image designer
gui-image-studio-generate: Generate embedded image resources from folders
gui-image-studio-create-samples: Create sample images for testing
All tools are automatically installed and available in your PATH when you install GUI Image Studio.
gui-image-studio-designer
Launch the visual image designer application.
Basic Usage
# Launch the designer
gui-image-studio-designer
# Launch with specific file
gui-image-studio-designer --file image.png
# Launch in fullscreen mode
gui-image-studio-designer --fullscreen
Command Options
gui-image-studio-designer [OPTIONS] [FILE]
Options:
--file PATH Open specific image file on startup
--new Start with new blank image
--fullscreen Launch in fullscreen mode
--theme THEME Set initial theme (light/dark/system)
--size WIDTHxHEIGHT Set initial window size
--help Show help message
--version Show version information
Examples
# Open specific image
gui-image-studio-designer --file photos/vacation.jpg
# Start with new image in fullscreen
gui-image-studio-designer --new --fullscreen
# Set window size and theme
gui-image-studio-designer --size 1200x800 --theme dark
# Show version
gui-image-studio-designer --version
Integration with File Managers
You can integrate the designer with your file manager for easy access:
Windows (Registry):
# Add "Edit with GUI Image Studio" to context menu
reg add "HKEY_CLASSES_ROOT\*\shell\EditWithGUIImageStudio" /ve /d "Edit with GUI Image Studio"
reg add "HKEY_CLASSES_ROOT\*\shell\EditWithGUIImageStudio\command" /ve /d "gui-image-studio-designer --file \"%1\""
Linux (Desktop Entry):
# ~/.local/share/applications/gui-image-studio.desktop
[Desktop Entry]
Name=GUI Image Studio
Comment=Visual image editor and processor
Exec=gui-image-studio-designer %f
Icon=gui-image-studio
Terminal=false
Type=Application
Categories=Graphics;Photography;
MimeType=image/png;image/jpeg;image/gif;image/bmp;
macOS (Automator Service):
Create an Automator service that runs:
gui-image-studio-designer --file "$@"
gui-image-studio-generate
Generate embedded Python modules from image folders.
Basic Usage
# Generate from folder
gui-image-studio-generate --folder images/
# Specify output file
gui-image-studio-generate --folder icons/ --output resources.py
# Set compression quality
gui-image-studio-generate --folder photos/ --quality 75
Command Options
gui-image-studio-generate [OPTIONS]
Required:
--folder PATH Input folder containing images
Optional:
--output FILE Output Python file (default: embedded_images.py)
--quality INT Compression quality 1-100 (default: 85)
--recursive Process subfolders recursively
--formats LIST Include only specific formats (comma-separated)
--exclude PATTERN Exclude files matching pattern
--prefix STRING Add prefix to image names
--module-name NAME Set module name in generated file
--help Show help message
--version Show version information
Examples
# Basic generation
gui-image-studio-generate --folder assets/images/
# High-quality icons
gui-image-studio-generate \
--folder icons/ \
--output src/icons.py \
--quality 95
# Recursive processing with format filter
gui-image-studio-generate \
--folder project/assets/ \
--output resources/all_images.py \
--recursive \
--formats png,jpg,gif
# Exclude temporary files
gui-image-studio-generate \
--folder images/ \
--exclude "*.tmp,*_backup.*,*.DS_Store"
# Add prefix to image names
gui-image-studio-generate \
--folder ui_icons/ \
--output ui_resources.py \
--prefix ui_
Advanced Usage Patterns
Build System Integration:
# Makefile target
generate-resources:
gui-image-studio-generate \
--folder src/assets/ \
--output src/resources.py \
--quality 90 \
--recursive
# Package.json script
{
"scripts": {
"build-images": "gui-image-studio-generate --folder assets/ --output src/images.py"
}
}
Batch Processing Multiple Folders:
#!/bin/bash
# generate_all_resources.sh
# Generate icons
gui-image-studio-generate \
--folder assets/icons/ \
--output src/resources/icons.py \
--quality 95
# Generate images
gui-image-studio-generate \
--folder assets/images/ \
--output src/resources/images.py \
--quality 80
# Generate backgrounds
gui-image-studio-generate \
--folder assets/backgrounds/ \
--output src/resources/backgrounds.py \
--quality 70
CI/CD Integration:
# GitHub Actions
name: Generate Image Resources
on:
push:
paths:
- 'assets/**'
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install GUI Image Studio
run: pip install gui-image-studio
- name: Generate resources
run: |
gui-image-studio-generate \
--folder assets/ \
--output src/resources.py \
--recursive \
--quality 85
- name: Commit changes
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add src/resources.py
git commit -m "Update image resources" || exit 0
git push
gui-image-studio-create-samples
Create sample images for testing and development.
Basic Usage
# Create samples in default location
gui-image-studio-create-samples
# Create in specific directory
gui-image-studio-create-samples --output test_images/
# Create specific number of samples
gui-image-studio-create-samples --count 20
Command Options
gui-image-studio-create-samples [OPTIONS]
Optional:
--output DIR Output directory (default: sample_images)
--count INT Number of samples to create (default: 10)
--size WIDTHxHEIGHT Sample image size (default: 64x64)
--formats LIST Image formats to create (default: png,jpg)
--animated Include animated GIF samples
--prefix STRING Filename prefix (default: sample_)
--help Show help message
--version Show version information
Examples
# Create default samples
gui-image-studio-create-samples
# Create large samples
gui-image-studio-create-samples \
--output large_samples/ \
--size 256x256 \
--count 15
# Create samples with animation
gui-image-studio-create-samples \
--output test_data/ \
--animated \
--formats png,jpg,gif
# Create samples with custom prefix
gui-image-studio-create-samples \
--output icons/ \
--prefix icon_ \
--size 32x32
Use Cases
Testing and Development:
# Create test data for unit tests
gui-image-studio-create-samples --output tests/fixtures/
# Create samples for UI development
gui-image-studio-create-samples \
--output ui_mockups/ \
--size 128x128 \
--count 25
Documentation and Examples:
# Create samples for documentation
gui-image-studio-create-samples \
--output docs/examples/ \
--formats png \
--size 64x64
Performance Testing:
# Create large dataset for performance testing
gui-image-studio-create-samples \
--output perf_test/ \
--count 1000 \
--size 512x512
Automation and Scripting
Shell Scripts
Complete Build Script:
#!/bin/bash
# build_resources.sh - Complete resource build script
set -e # Exit on error
echo "Building GUI Image Studio Resources..."
# Configuration
ASSETS_DIR="assets"
OUTPUT_DIR="src/resources"
TEMP_DIR="temp_build"
# Create directories
mkdir -p "$OUTPUT_DIR"
mkdir -p "$TEMP_DIR"
# Function to generate resources
generate_resources() {
local folder=$1
local output=$2
local quality=${3:-85}
echo "Generating $output from $folder..."
gui-image-studio-generate \
--folder "$ASSETS_DIR/$folder" \
--output "$OUTPUT_DIR/$output" \
--quality "$quality" \
--recursive
if [ $? -eq 0 ]; then
echo "✓ Generated $output"
else
echo "✗ Failed to generate $output"
exit 1
fi
}
# Generate different resource types
generate_resources "icons" "icons.py" 95
generate_resources "images" "images.py" 80
generate_resources "backgrounds" "backgrounds.py" 70
# Create test samples if needed
if [ "$1" = "--with-samples" ]; then
echo "Creating test samples..."
gui-image-studio-create-samples \
--output "$TEMP_DIR/samples" \
--count 10
echo "✓ Created test samples"
fi
# Cleanup
rm -rf "$TEMP_DIR"
echo "✓ Resource build complete!"
Windows Batch Script:
@echo off
REM build_resources.bat - Windows resource build script
echo Building GUI Image Studio Resources...
REM Configuration
set ASSETS_DIR=assets
set OUTPUT_DIR=src\resources
set QUALITY=85
REM Create output directory
if not exist "%OUTPUT_DIR%" mkdir "%OUTPUT_DIR%"
REM Generate icons
echo Generating icons...
gui-image-studio-generate ^
--folder "%ASSETS_DIR%\icons" ^
--output "%OUTPUT_DIR%\icons.py" ^
--quality 95
if errorlevel 1 (
echo Failed to generate icons
exit /b 1
)
REM Generate images
echo Generating images...
gui-image-studio-generate ^
--folder "%ASSETS_DIR%\images" ^
--output "%OUTPUT_DIR%\images.py" ^
--quality %QUALITY%
if errorlevel 1 (
echo Failed to generate images
exit /b 1
)
echo Resource build complete!
Python Automation Scripts
Advanced Build Script:
#!/usr/bin/env python3
"""
Advanced build script for GUI Image Studio resources.
"""
import os
import sys
import subprocess
import argparse
from pathlib import Path
class ResourceBuilder:
def __init__(self, config):
self.config = config
self.assets_dir = Path(config['assets_dir'])
self.output_dir = Path(config['output_dir'])
def ensure_directories(self):
"""Create necessary directories."""
self.output_dir.mkdir(parents=True, exist_ok=True)
def run_command(self, cmd):
"""Run command and handle errors."""
try:
result = subprocess.run(
cmd,
shell=True,
check=True,
capture_output=True,
text=True
)
return True, result.stdout
except subprocess.CalledProcessError as e:
return False, e.stderr
def generate_resources(self, folder, output_file, quality=85):
"""Generate resources from folder."""
input_path = self.assets_dir / folder
output_path = self.output_dir / output_file
if not input_path.exists():
print(f"Warning: Input folder {input_path} does not exist")
return False
cmd = [
"gui-image-studio-generate",
"--folder", str(input_path),
"--output", str(output_path),
"--quality", str(quality),
"--recursive"
]
print(f"Generating {output_file} from {folder}...")
success, output = self.run_command(" ".join(cmd))
if success:
print(f"✓ Generated {output_file}")
return True
else:
print(f"✗ Failed to generate {output_file}: {output}")
return False
def create_samples(self, output_dir, count=10):
"""Create sample images."""
sample_path = Path(output_dir)
sample_path.mkdir(parents=True, exist_ok=True)
cmd = [
"gui-image-studio-create-samples",
"--output", str(sample_path),
"--count", str(count)
]
print(f"Creating {count} sample images...")
success, output = self.run_command(" ".join(cmd))
if success:
print(f"✓ Created samples in {sample_path}")
return True
else:
print(f"✗ Failed to create samples: {output}")
return False
def build_all(self):
"""Build all resources."""
self.ensure_directories()
# Resource configurations
resources = [
("icons", "icons.py", 95),
("images", "images.py", 80),
("backgrounds", "backgrounds.py", 70),
("ui", "ui_elements.py", 90)
]
success_count = 0
for folder, output_file, quality in resources:
if self.generate_resources(folder, output_file, quality):
success_count += 1
print(f"\nBuild complete: {success_count}/{len(resources)} successful")
return success_count == len(resources)
def main():
parser = argparse.ArgumentParser(description="Build GUI Image Studio resources")
parser.add_argument("--assets", default="assets", help="Assets directory")
parser.add_argument("--output", default="src/resources", help="Output directory")
parser.add_argument("--samples", action="store_true", help="Create sample images")
parser.add_argument("--config", help="Configuration file")
args = parser.parse_args()
# Configuration
config = {
'assets_dir': args.assets,
'output_dir': args.output
}
# Load config file if provided
if args.config and os.path.exists(args.config):
import json
with open(args.config) as f:
config.update(json.load(f))
# Build resources
builder = ResourceBuilder(config)
if builder.build_all():
print("✓ All resources built successfully")
# Create samples if requested
if args.samples:
builder.create_samples("temp/samples")
sys.exit(0)
else:
print("✗ Some resources failed to build")
sys.exit(1)
if __name__ == "__main__":
main()
Configuration Files
JSON Configuration:
{
"assets_dir": "assets",
"output_dir": "src/resources",
"resources": [
{
"folder": "icons",
"output": "icons.py",
"quality": 95,
"formats": ["png", "svg"]
},
{
"folder": "images",
"output": "images.py",
"quality": 80,
"exclude": ["*.tmp", "*_backup.*"]
},
{
"folder": "backgrounds",
"output": "backgrounds.py",
"quality": 70,
"recursive": true
}
],
"samples": {
"enabled": true,
"output": "test_samples",
"count": 15,
"size": "64x64"
}
}
YAML Configuration:
# gui-image-studio.yml
assets_dir: assets
output_dir: src/resources
resources:
- folder: icons
output: icons.py
quality: 95
formats: [png, svg]
- folder: images
output: images.py
quality: 80
exclude: ["*.tmp", "*_backup.*"]
- folder: backgrounds
output: backgrounds.py
quality: 70
recursive: true
samples:
enabled: true
output: test_samples
count: 15
size: "64x64"
IDE Integration
Visual Studio Code
Tasks Configuration (.vscode/tasks.json):
{
"version": "2.0.0",
"tasks": [
{
"label": "Generate Image Resources",
"type": "shell",
"command": "gui-image-studio-generate",
"args": [
"--folder", "assets/",
"--output", "src/resources.py",
"--quality", "85"
],
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared"
},
"problemMatcher": []
},
{
"label": "Create Sample Images",
"type": "shell",
"command": "gui-image-studio-create-samples",
"args": [
"--output", "test_samples/",
"--count", "10"
],
"group": "test"
},
{
"label": "Launch Designer",
"type": "shell",
"command": "gui-image-studio-designer",
"args": ["${file}"],
"group": "build"
}
]
}
Keyboard Shortcuts (.vscode/keybindings.json):
[
{
"key": "ctrl+shift+g",
"command": "workbench.action.tasks.runTask",
"args": "Generate Image Resources"
},
{
"key": "ctrl+shift+d",
"command": "workbench.action.tasks.runTask",
"args": "Launch Designer"
}
]
PyCharm Integration
External Tools Configuration:
Go to File → Settings → Tools → External Tools
Add new tool:
Name: Generate Image Resources
Program: gui-image-studio-generate
Arguments: --folder assets/ --output src/resources.py
Working directory: $ProjectFileDir$
Add keyboard shortcut in Keymap settings
Docker Integration
Dockerfile for CLI Tools
FROM python:3.10-slim
# Install system dependencies
RUN apt-get update && apt-get install -y \
python3-tk \
&& rm -rf /var/lib/apt/lists/*
# Install GUI Image Studio
RUN pip install gui-image-studio
# Set working directory
WORKDIR /workspace
# Default command
CMD ["gui-image-studio-generate", "--help"]
Usage:
# Build image
docker build -t gui-image-studio-cli .
# Generate resources
docker run -v $(pwd):/workspace gui-image-studio-cli \
gui-image-studio-generate --folder assets/ --output resources.py
# Create samples
docker run -v $(pwd):/workspace gui-image-studio-cli \
gui-image-studio-create-samples --output samples/
Docker Compose for Development
version: '3.8'
services:
gui-image-studio:
build: .
volumes:
- ./assets:/workspace/assets
- ./src:/workspace/src
environment:
- DISPLAY=${DISPLAY}
command: >
bash -c "
gui-image-studio-generate --folder assets/ --output src/resources.py &&
gui-image-studio-create-samples --output test_samples/
"
Troubleshooting CLI Tools
Common Issues
Command Not Found:
# Check if GUI Image Studio is installed
pip show gui-image-studio
# Reinstall if necessary
pip install --force-reinstall gui-image-studio
# Check PATH
echo $PATH
Permission Errors:
# Linux/macOS: Check file permissions
ls -la /usr/local/bin/gui-image-studio-*
# Windows: Run as administrator
# Right-click Command Prompt → "Run as administrator"
Import Errors:
# Check Python environment
python -c "import gui_image_studio; print('OK')"
# Check dependencies
pip install --upgrade Pillow
Display Issues (Linux):
# For headless systems
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 &
# Install X11 forwarding for SSH
ssh -X user@server
Debugging and Logging
Enable Verbose Output:
# Most CLI tools support verbose mode
gui-image-studio-generate --folder assets/ --verbose
# Or set environment variable
export GUI_IMAGE_STUDIO_DEBUG=1
gui-image-studio-generate --folder assets/
Log Files:
# Redirect output to log file
gui-image-studio-generate --folder assets/ > build.log 2>&1
# View logs
tail -f build.log
Best Practices
CLI Usage Guidelines
Use absolute paths when possible
Validate inputs before processing
Handle errors gracefully in scripts
Use configuration files for complex setups
Document your build processes
# Good: Explicit and safe
gui-image-studio-generate \
--folder "$(pwd)/assets/icons" \
--output "$(pwd)/src/resources/icons.py" \
--quality 95
# Check for errors
if [ $? -ne 0 ]; then
echo "Failed to generate resources"
exit 1
fi
Performance Optimization
# Process smaller batches for large folders
find assets/ -name "*.png" | head -100 | xargs -I {} \
gui-image-studio-generate --folder {} --output batch1.py
# Use parallel processing
parallel gui-image-studio-generate --folder {} --output {/.}.py ::: assets/*/
Security Considerations
# Validate input paths
if [[ "$INPUT_FOLDER" =~ ^[a-zA-Z0-9/_-]+$ ]]; then
gui-image-studio-generate --folder "$INPUT_FOLDER"
else
echo "Invalid folder path"
exit 1
fi
# Use temporary directories safely
TEMP_DIR=$(mktemp -d)
trap "rm -rf $TEMP_DIR" EXIT
Next Steps
Now that you understand the command-line tools:
Learn Scripting: scripting
Explore GUI Development: gui_development
Try Advanced Examples: Examples
Integrate with Your Workflow: Start automating your image processing tasks!