Skip to content

meltforce/immich-bulk-share-cli

BranchesTags

Repository files navigation

immich-bulk-share-cli

🚀 Community Tool: Bulk manage album sharing permissions in Immich via CSV files

A Python CLI tool for managing album sharing permissions in Immich (open-source photo management). Since Immich currently lacks native bulk sharing functionality, this tool fills that gap by allowing you to manage permissions for hundreds of albums at once through CSV files.

Why This Tool?

Immich is excellent for organizing photos, but manually sharing hundreds of albums with family members is tedious. This tool was created to:

  • Save Time: Share 150+ albums in minutes instead of hours
  • Maintain Consistency: Apply same permissions across multiple albums
  • Track Changes: CSV-based approach provides audit trail
  • Safe Testing: Dry-run mode lets you preview changes before applying

⚠️ Development Status

Honest Disclosure: This tool was created through rapid prototyping ("vibe coding") to solve a specific personal need. While it has been thoroughly refactored and tested, please be aware:

  • 🛠️ Limited Support: This is a side project with minimal ongoing support
  • 🔄 Minimal Future Development: No major feature additions planned
  • 🤝 Community-Driven: Pull requests welcome, but review/merge may be slow
  • ✅ Works as Intended: The current feature set is stable and tested
  • 📝 Use at Your Own Risk: Always test with --dry-run first

Recommendation: If you need enterprise-grade support or extensive features, wait for native Immich functionality (Discussion #2228) or fork this project for your needs.

Quick Start

# 1. Install dependencies
pip install requests

# 2. Login and test connection
python album_processor.py login --url https://your-immich-server --api-key YOUR_API_KEY

# 3. Export current album permissions
python album_processor.py list-all --output albums.csv

# 4. Edit albums.csv with your desired changes

# 5. Preview changes (dry-run)
python album_processor.py share-albums --input albums.csv --dry-run

# 6. Apply changes
python album_processor.py share-albums --input albums.csv

Key Features

Core Functionality

  • List & Export: Export all albums with permissions, dates, and photo counts to CSV
  • Bulk Updates: Update sharing permissions for multiple albums from CSV file
  • Automatic Sync: Adds/updates/removes users based on CSV content

Security & Safety

  • 1Password Integration: Secure credential storage when 1Password CLI is available
  • Dry-Run Mode: Preview all changes before applying them
  • Input Validation: Email and role validation with detailed warnings
  • CSV Injection Protection: Automatic sanitization of dangerous values
  • HTTPS Warnings: Security alerts for unencrypted connections

Usability

  • Flexible CSV Support: Auto-detects comma, semicolon, or tab delimiters
  • Progress Tracking: Real-time progress with configurable verbosity
  • Smart Sorting: Albums sorted by first photo date (newest first)
  • Comprehensive Logging: Structured logging with clear error messages

Requirements

  • Python 3.6+
  • requests library

Installation

pip install requests

Usage

The script provides three main commands: login, list-all, and share-albums. Here's the basic CLI help:

usage: album_processor.py [-h] {list-all,share-albums,login} ...

Process and share albums via API.

positional arguments:
  {list-all,share-albums,login}
                        Command to execute
    list-all            List all albums and their sharing permissions
    share-albums        Update album sharing permissions from CSV
    login               Save and validate API credentials for future use

options:
  -h, --help            show this help message and exit

Authentication (login)

Before using the script, you need to configure your API credentials. They will be stored securely in ~/.config/immich-bulk-share.

# Save credentials
python album_processor.py login --url https://your-immich-server --api-key YOUR_API_KEY

# Test connection without saving credentials
python album_processor.py login --url https://your-immich-server --api-key YOUR_API_KEY --dry-run

Listing Albums (list-all)

The list-all command exports all albums and their sharing permissions to a CSV file.

# Export to default filename (albums_YYYYMMDD_HHMMSS.csv)
python album_processor.py list-all

# Export to specific filename
python album_processor.py list-all --output albums.csv

# Preview what would be exported
python album_processor.py list-all --dry-run

Managing Shares (share-albums)

The share-albums command updates album sharing permissions from a CSV file.

# Update sharing permissions
python album_processor.py share-albums --input albums.csv

# Preview changes without applying them
python album_processor.py share-albums --input albums.csv --dry-run

Control output verbosity:

# Quiet mode - shows only progress counter
python album_processor.py share-albums --input albums.csv --quiet

# Verbose mode (default) - shows detailed information for each album
python album_processor.py share-albums --input albums.csv --verbose

CSV Format

Structure

Required columns:

  • AlbumName
  • AlbumId
  • Role
  • User columns (User 1, User 2, etc.)

Additional information columns:

  • FirstPhoto (date of the first photo in album)
  • LastPhoto (date of the last photo in album)
  • Photos (number of photos in album)

Example:

AlbumName;AlbumId;FirstPhoto;LastPhoto;Photos;Role;User 1;User 2
Vacation 2023;abc123;2023-01-01 12:00;2023-01-07 18:30;150;viewer;user1@example.com;user2@example.com
Holiday Photos;def456;2023-12-24 10:00;2023-12-26 22:15;75;editor;user3@example.com;

Processing Rules

  • Users will be added to albums with specified roles
  • Existing users' roles will be updated if different
  • Users not in CSV will be removed from album
  • Empty cells are ignored
  • Albums are automatically sorted by first photo date (newest first)

Error Handling

The script handles:

  • Network connectivity issues
  • Server timeouts
  • Invalid CSV formats
  • Missing users
  • Invalid URLs
  • Invalid credentials

Operation results include:

  • Number of processed albums
  • Successful/failed updates
  • Removed users
  • List of users not found

Security

Credential Storage

Recommended: 1Password CLI Integration

The tool automatically detects and uses 1Password CLI for secure credential storage:

How it works:

  1. Install 1Password CLI: brew install 1password-cli (macOS) or see installation guide
  2. Sign in to 1Password CLI: op signin
  3. Run the login command - credentials are automatically stored in 1Password
  4. The tool creates/updates a 1Password item named immich-bulk-share-cli

Item Structure:

  • Title: immich-bulk-share-cli (automatically created)
  • Category: API Credential
  • Fields:
    • url: Your Immich server URL
    • password: Your API key

Manual Setup (Optional):

If you prefer to create the 1Password item manually:

# Create the item manually
op item create \
  --category="api-credential" \
  --title="immich-bulk-share-cli" \
  url=https://your-immich-server \
  password=YOUR_API_KEY

# Verify it was created
op item get immich-bulk-share-cli

Customization Options:

To customize 1Password integration, edit config.json in the project directory:

{
  "op_item_name": "immich-bulk-share-cli",
  "op_url_field": "url",
  "op_password_field": "password"
}

This file is automatically created with default values on first run. You can customize:

  • op_item_name: Change the 1Password item name (e.g., for multiple Immich servers)
  • op_url_field: URL field name (e.g., "URL", "Webseite" for German)
  • op_password_field: Password field name (e.g., "Passwort", "mot de passe" for French)

Note: config.json is in .gitignore and won't be committed to the repository

Localization Support:

The tool automatically detects common field names in multiple languages:

  • URL field: url, URL, website, Webseite
  • Password field: password, Passwort, mot de passe, api key, api-key

Finding Your Field Names:

If credentials aren't loading correctly, check your actual field names:

# View the 1Password item structure
op item get immich-bulk-share-cli --format=json

# Look for "id" and "label" in the "fields" array
# Update config.json with the correct field names

Fallback: File Storage

  • Credentials stored in ~/.config/immich-bulk-share/config.json
  • Config file permissions set to 600 (user read/write only)
  • ⚠️ Warning: API keys stored in plaintext - consider using 1Password CLI for better security

Network Security

  • HTTPS Recommended: The tool warns when using HTTP connections
  • SSL Verification: Certificate validation enabled by default
  • Security Warnings: Clear alerts for insecure configurations

Data Protection

  • CSV Injection Prevention: Automatic sanitization of CSV values
  • Input Validation: Email and role validation before processing
  • Dry-run Mode: Test changes without applying them

Best Practices

  1. Always use HTTPS URLs for your Immich server
  2. Install 1Password CLI for secure credential management
  3. Use dry-run mode to preview changes before applying
  4. Regularly rotate your API keys
  5. Keep the tool updated for latest security fixes

Testing

The project includes unit tests to ensure code quality:

# Run tests with unittest
python -m unittest test_album_processor.py

# Or with pytest (if installed)
pip install pytest
pytest test_album_processor.py

Test Coverage: 9 test cases covering validation, sanitization, and configuration

Troubleshooting

Connection Issues

Problem: Cannot reach the server

# Check if server is reachable
curl -H "x-api-key: YOUR_API_KEY" https://your-immich-server/api/server/about

# Test with --dry-run to verify credentials
python album_processor.py login --url YOUR_URL --api-key YOUR_KEY --dry-run

Problem: SSL certificate verification failed

# For self-signed certificates, ensure they're properly configured
# The tool explicitly enables SSL verification for security

Authentication Issues

Problem: Authentication failed - check your API key

# Generate a new API key in Immich:
# Settings → Account → API Keys → Create New

1Password CLI Issues

Problem: 1Password CLI not detected

# Check if 1Password CLI is installed
which op
op --version

# Install 1Password CLI
# macOS:
brew install 1password-cli

# Linux/Windows: See https://developer.1password.com/docs/cli/get-started/

Problem: Failed to save to 1Password

# Ensure you're signed in to 1Password CLI
op signin

# Check if you have the correct vault access
op vault list

# Test creating an item manually
op item create --category=login --title=test

# If still failing, check 1Password CLI logs:
op --debug item get immich-bulk-share-cli

Problem: Tool uses file storage instead of 1Password

# Verify 1Password CLI is in PATH
echo $PATH
which op

# Sign in again
op signin

# Run login command again
python album_processor.py login --url YOUR_URL --api-key YOUR_KEY

Problem: Could not find URL or API key fields in 1Password item (Non-English 1Password)

# Check your actual field names
op item get immich-bulk-share-cli --format=json | grep -A5 '"fields"'

# Example output:
# "fields": [
#   {"id": "url", "label": "Webseite", "value": "..."},
#   {"id": "password", "label": "Passwort", "value": "..."}
# ]

# If field names are different, update config.json:
# {
#   "op_item_name": "immich-bulk-share-cli",
#   "op_url_field": "Webseite",
#   "op_password_field": "Passwort"
# }

CSV Issues

Problem: Invalid CSV format. Required columns not found

# Ensure your CSV has these columns:
# AlbumName, AlbumId, Role, User 1, User 2, ...

# Export a fresh template:
python album_processor.py list-all --output template.csv

Problem: Skipping invalid email: xyz

  • Check email format in CSV (must be valid email address)
  • Email validation uses pattern: user@domain.tld

Performance

Problem: Processing is slow

# Increase timeout for slow connections (default: 10s)
# Edit album_processor.py, change DEFAULT_TIMEOUT = 10 to higher value

# Use --quiet mode to reduce output overhead
python album_processor.py share-albums --input albums.csv --quiet

FAQ

Q: Does this tool modify photos or albums themselves? A: No, it only modifies sharing permissions. Photos and album content are never touched.

Q: Will users not in the CSV be removed from albums? A: Yes, the tool synchronizes permissions. Users not listed will be removed. Use dry-run first!

Q: Can I share albums with external users (public links)? A: No, this tool manages user-based sharing within your Immich instance. For public links, use Immich's built-in sharing feature.

Q: Is my API key secure? A: If you have 1Password CLI installed, keys are stored securely in 1Password (item name: immich-bulk-share-cli). Otherwise, they're stored in plaintext in ~/.config/immich-bulk-share/config.json (with restricted permissions).

Q: How do I check if 1Password CLI integration is working? A: When you run login, you'll see either:

  • "1Password CLI detected - using secure credential storage" ✅
  • "1Password CLI not found - credentials will be stored in plaintext" ⚠️

You can also verify manually: op item get immich-bulk-share-cli

Q: Can I use multiple Immich servers with 1Password? A: Yes! For multiple servers, customize the op_item_name in config.json:

  • Create different config.json files for each server installation
  • Each can reference a different 1Password item name
  • Example: "op_item_name": "immich-bulk-share-cli-server2"

Q: Why doesn't 1Password integration work with German/French/other languages? A: The tool now supports multiple languages automatically (German: "Passwort", "Webseite"; French: "mot de passe"). If it still doesn't work:

  1. Run op item get immich-bulk-share-cli --format=json to see your field names
  2. Update op_url_field and op_password_field in config.json if needed
  3. See the Troubleshooting section for details

Q: Can I use this with Immich cloud/hosted instances? A: Yes, as long as you have API access and valid credentials.

Q: What happens if I accidentally share albums with the wrong people? A: Export current state first (list-all), then you can always restore by re-running with the original CSV.

Q: Does this work with Immich's partner sharing feature? A: No, this is for album-level sharing. Partner sharing is a separate feature in Immich.

Changelog

See CHANGELOG.md for detailed version history and migration guides.

Exit Codes

  • 0: Success
  • 1: Error (file not found, network error, invalid credentials, etc.)

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Development

# Clone the repository
git clone https://github.com/meltforce/immich-bulk-share-cli.git
cd immich-bulk-share-cli

# Run tests
python -m unittest test_album_processor.py

# Make your changes and test thoroughly with dry-run mode
python album_processor.py share-albums --input test.csv --dry-run

Related Projects

Acknowledgments

  • Thanks to the Immich team for creating an amazing open-source photo management solution
  • Community members who requested bulk sharing features (#2228)
  • Contributors to this project

Support

Expected Response Time: ⏱️ Days to weeks (or longer)

This is a side project with limited support capacity. Here's what you can expect:

  • Issues: Bug reports welcome via GitHub Issues

    • Critical security issues: Priority response
    • Bugs: Best effort, may take time
    • Feature requests: Unlikely to be implemented

  • Pull Requests: Community contributions appreciated, but review/merge may be slow

  • Community Help: Try Immich Discussions for general questions

  • Documentation: This README and CHANGELOG.md should cover most use cases

Alternative: If you need immediate support or custom features, consider forking the project or hiring a developer familiar with Python.

License

MIT

Made with ❤️ for the Immich community

About

Bulk album sharing for Immich

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

13 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages