Import Existing

import-existing

Scan a local directory and mark matching iCloud assets as already downloaded in the state database. The next sync skips those files instead of re-downloading them.

Usage

Put the directory and path-shaping settings in TOML:

[auth]
username = "my@email.address"

[download]
directory = "/photos"
folder_structure = "%Y/%m/%d"

[photos]
resolution = "original"

Then run:

kei import-existing --config ~/.config/kei/config.toml

Dry run first when you're not sure the config matches the tree:

kei import-existing --config ~/.config/kei/config.toml --dry-run

When to use it

• Migrating from Python icloudpd or another downloader.
• Recovering after a database reset when files are still on disk.
• Adopting kei on a directory that was populated before kei.

See Migration from Python for the full workflow.

Matching rules

import-existing signs in, enumerates selected iCloud assets, computes the paths kei would use, and adopts local files with the expected path and size. It stores kei's SHA-256 for future verification.

Repeated imports keep a size and mtime snapshot. If an adopted local file has not changed, a later import can skip re-reading the whole file for SHA-256 and move on faster.

For a safer first pass, use strict mode:

kei import-existing --config ~/.config/kei/config.toml --strict

Strict mode fetches a small prefix from iCloud and compares it with the local file before adopting a same-name, same-size match.

Config it reads

Import uses the same path derivation settings as sync:

Setting	TOML
Directory	[download].directory
Folder templates	[download].folder_structure*
File match policy	[photos].file_match_policy
Resolution and extras	[photos].resolution, edited, alternative, raw_policy, force_resolution
Live photo behavior	[photos].live_photo_mode, live_resolution, live_photo_mov_filename_policy
Unicode filename policy	[photos].keep_unicode_in_filenames
Libraries, albums, smart folders, unfiled	[filters].libraries, [filters].albums, [filters].smart_folders, [filters].unfiled
Media filters	[filters].media

If the config doesn't match the old tree, files land in the unmatched bucket and the next sync may download another copy.

Explicit albums and smart folders are collection-scoped here too. A named album or smart folder can adopt matching files from shared libraries even when unfiled import remains scoped by [filters].libraries.

Runtime flags

Flag	Description
--config	TOML config path
--library	One-run library scope for import. Same grammar as [filters].libraries
--recent	Only check N recent assets. Count form only; the 30d days form is sync-only
--dry-run	Report matches without writing state rows
--strict	Verify a cloud prefix before adopting
--force-empty	Override the empty-library safety guard
--no-progress-bar	Disable progress bar
--password, --password-file, --password-command	Password sources for this run

Related

• State Tracking
• Migration from Python
• Configuration