You need to be crazy to use this fork in production. There is no support, no warranty, and no guarantee that it will work as expected. Use at your own risk. You could destroy your data and lose everything. You have been warned.
Standalone command-line tool for Ente Photos with upload and folder watching capabilities.
This is a fork of the official ente-io/ente repository, cleaned up to contain only the CLI tool with extended functionality.
The Ente CLI was originally developed by the Ente team for:
- Exporting photos/videos to create local backups
- Account management and basic file operations
This fork adds:
- Upload: Upload images to Ente Photos with end-to-end encryption
- Watch: Automatically upload new images from monitored folders
- Support for albums, deduplication, and smart duplicate detection
- Download all your photos and videos from Ente Photos
- Create local backups with original quality
- Supports incremental exports
- Upload single or multiple images with end-to-end encryption
- Batch upload with configurable concurrency
- Smart deduplication (skip already-uploaded files)
- Album organization and management
- Progress tracking for large uploads
- Monitor folders for new images and auto-upload
- Three modes:
- Default: Upload all to "CLI Uploads" album
- Specified Album (
--album): Upload all to user-specified album - Folder-as-Album (
--folder-albums): Each subfolder becomes a separate album
- Duplicate detection with automatic album assignment
- Graceful shutdown and state recovery
- Account management (add, list, update)
- Auth token decryption
- Admin functions for self-hosted instances
- End-to-end encryption using Ente's proven security model
- All files encrypted client-side before upload
- Per-file encryption keys, encrypted with collection keys
- Server only sees encrypted blobs
- Compatible with all official Ente clients (web, mobile, desktop)
The easiest way is to download a pre-built binary from the GitHub releases.
- Go 1.20 or higher
- FFmpeg (for thumbnail generation)
cd cli
./release.shcd cli
go build -o bin/ente main.goThe generated binaries are standalone, static binaries with no dependencies. You can run them directly, or put them somewhere in your PATH.
There is also an option to use Docker.
Run the help command to see all available commands:
ente --helpIf you wish, you can add multiple accounts (your own and that of your family members) and export all data using this tool.
ente account addNote
ente account add does not create new accounts, it just adds pre-existing accounts to the list of accounts that the CLI knows about so that you can use them for other actions.
ente account listente account update --app auth/photos --email email@domain.com --dir ~/photosExport all photos and videos:
ente exportente upload photo.jpgente upload photo.jpg --album "Vacation 2024"ente upload *.jpg --album "Summer"ente upload /path/to/photos -r --workers=8ente watch ~/Photosente watch ~/Photos --album "Family Photos"Each subfolder becomes a separate album:
ente watch ~/Photos --folder-albumsStop watching by pressing Ctrl+C for graceful shutdown with state preservation.
You can view more CLI documentation at cli/docs/generated/ente.md.
To update the docs, run:
cd cli
go run main.go docsIf you fancy Docker, you can also run the CLI within a container.
Modify the docker-compose.yml and add volume. cli-data volume is mandatory, you can add more volumes for your export directory.
Build and run the container in detached mode:
docker-compose up -d --buildNote that BuildKit is needed to build this image. If you face this issue, a quick fix is to add DOCKER_BUILDKIT=1 in front of the build command.
Execute commands in the container:
docker-compose exec ente-cli /bin/sh -c "./ente-cli version"
docker-compose exec ente-cli /bin/sh -c "./ente-cli account add"
docker-compose exec ente-cli /bin/sh -c "./ente-cli upload photo.jpg"
docker-compose exec ente-cli /bin/sh -c "./ente-cli watch /path/to/photos"For self-hosting configuration, see cli/docs/selfhost.md.
This repository includes the architecture/ directory from the upstream Ente project, which contains detailed documentation on:
- End-to-end encryption model
- Key derivation and management
- Cryptographic primitives (libsodium, ChaCha20-Poly1305)
- Security audits and specifications
See architecture/README.md for complete details.
- File discovery and hash computation
- Deduplication check (local + remote)
- Metadata extraction (EXIF)
- Thumbnail generation (FFmpeg)
- Client-side encryption (file, thumbnail, metadata)
- S3 upload to presigned URLs
- Finalization via Museum API
If a file is already uploaded:
- File is NOT re-uploaded (saves bandwidth and time)
- File is added to the target album (re-encrypts file key with collection key)
- Uses content hash for reliable deduplication
For the full Ente ecosystem including web, mobile, desktop apps, and the Museum API server, see:
- Main repository: https://github.com/ente-io/ente
- Website: https://ente.io
- Documentation: https://ente.io/help
cd cli
go test ./...Test specific packages:
go test ./pkg/uploader/...
go test ./pkg/watcher/...cd cli
go fmt ./...
go vet ./...cd cli
go run main.go docsContributions are welcome! When submitting pull requests:
- Keep commit messages concise (under 72 chars)
- Test your changes thoroughly
- Ensure
go fmtandgo vetpass - Update documentation if adding new features
This project inherits the license from the upstream ente-io/ente repository. See the LICENSE file for details.
If you discover a security vulnerability, please report it responsibly by emailing security@ente.io or using this link.
For questions about the upstream Ente platform, see:
For issues specific to this fork's upload/watch functionality, please open an issue in this repository.