CLI: feature request — list command for metadata-only file listing

[dustindoan]

Context

We're self-hosting Ente for a small co-op; this gap surfaced during Apple Photos → Ente migration work for the first household.

Background

The CLI today has ente export — pulls files + metadata. Useful but expensive when the consumer only needs metadata: every file blob is downloaded.

We'd like to propose a complementary list command that fetches and decrypts file metadata only, emitting it as JSON on stdout.

Related to #2347 (CLI upload feature request), but narrower in scope — read-only metadata listing, no protocol/crypto changes, useful as a building block for the kind of migration tooling that #2347 would eventually unlock.

Use case

Programmatic tooling, specifically:

• Migration tools that ask "is this file already uploaded?" without downloading anything
• Dedup checks (compare local file hashes against what's in Ente)
• Scripted backups / sync verification
• Any automation wanting a structured view of what's in Ente without paying the file-bytes cost

The load-bearing primitive is the content hash — Ente already stores it in encrypted metadata for its own dedup, and decrypting locally is enough to power these scenarios without downloading anything.

Proposed shape

ente list [--shared=false] [--hidden=false] [--albums a,b] [--exclude-albums c] [--emails user@x]

Output: newline-delimited JSON, one file per line. Proposed schema:

{"id":12345,"ownerID":67890,"title":"IMG_001.jpg","fileType":"image","fileSize":2133081,"hash":"…","creationTime":"2026-04-08T19:13:47Z","modificationTime":"2026-04-08T20:11:04Z","lastUpdateTime":1777097251270241,"latitude":49.96,"longitude":-125.23}

Hides crypto-internal fields (Key, FileNonce, ThumbnailNonce). Surfaces what's useful for scripting: identity, hash, timestamps, type, size, location, caption.

E2EE compatibility
Fully compatible. The encrypted metadata blobs and per-file keys are already independently fetchable from museum (the existing export client uses them in sequence). Metadata-only mode just stops after metadata fetch and skips the file-byte download. Bandwidth drops from MB/photo to KB/photo. Same crypto, no new server endpoints, no protocol changes.

Implementation status
We have a working Go POC built on top of the existing fetchRemoteCollections + fetchRemoteFiles paths in pkg/sync.go. Two new files only (cmd/list.go, pkg/list.go); no existing files modified. Tested against our self-hosted museum with ~31,000 files: full metadata sync in a few minutes (uncached) → sub-second JSON dump (cached). Zero malformed records.

Happy to share the code if useful.

Routing question
We noticed rust/cli/ is at v0.0.1 with account + export commands, while the Go CLI remains the only feature-complete option (admin commands etc.). Before opening a PR we want to ask:

1. Welcome a Go PR for list while feature-parity work continues in Rust?
2. Prefer Rust-first — wait until rust-cli reaches the right baseline, port there?
3. Both — land Go first, port to Rust as part of the parity push?
4. Something else entirely — different command shape, output format, or scope?

Happy to do the work in either language. The Go code is ready; based on inspecting rust/cli/src/sync/engine.rs, a Rust port is similar in shape (~150 lines).

What direction would you prefer?

[dustindoan]

Went ahead and built both implementations. Both are validated end-to-end against a self-hosted museum with ~31,000 files; outputs match at byte-level on the load-bearing fields.

Branches:

• Go: https://github.com/dustindoan/ente/tree/feature/list-command
• Rust: https://github.com/dustindoan/ente/tree/feature/list-command-rust

Diff sizes:

• Go: 2 new files (cli/cmd/list.go, cli/pkg/list.go), no existing files modified.
• Rust: 2 new files (rust/cli/src/cli/list.rs, rust/cli/src/commands/list.rs), small touches to 4 existing files (module wiring + changing visibility on 4 helper fns in commands::export from fn to pub fn so list can reuse the decryption pipeline). Refactor opportunity flagged for follow-up: extract the decrypt helpers to a shared commands::crypto module so they aren't coupled to export's namespace.

Performance note. The Rust port runs noticeably faster than the Go on the same library (single async pass via reqwest+tokio vs Go's paginated sequential fetches). Worth mentioning since the codebase appears to be transitioning toward Rust.