ukung-import

CLI for bulk-importing photos (e.g. from a local OneDrive sync folder) into ukung.com.

It walks a folder, reads EXIF, clusters photos into trips by time gaps, names each trip (date range, reverse-geocoded place, optionally AI), lets you review and edit the plan, then creates the trips and uploads the photos. Re-runs are resumable — a local ledger skips anything already uploaded.

Requirements

• Node.js 22.5+ — the upload ledger uses the built-in node:sqlite module, which is only available from Node 22.5.0 onward.

Quick start

# One-time: link this machine to your ukung.com account
npx ukung-import auth

# Scan + cluster + preview + upload a folder
npx ukung-import import "C:/Users/yourname/OneDrive/Pictures"

Working from a clone of this repo instead of the published package? Run the same commands as node bin/ukung-import.js <command>.

On first auth you'll be prompted for an API token. Generate one at https://ukung.com/profile → "API access" → Generate, copy it, and paste it when prompted. The token is stored at ~/.ukung/config.json (mode 600) and reused on every later run.

Commands

| Command | What it does | |---|---| | auth | Prompt for an API token, validate it against ukung.com, and save it to ~/.ukung/config.json. | | whoami | Print which account the CLI is currently authenticated as. | | logout | Forget the saved token locally (does not revoke it on the server — do that on the profile page). | | import <folder> | Walk a folder, cluster photos into trips, preview, then create trips and upload photos. |

import flags

| Flag | Default | Effect | |---|---|---| | --gap-hours N | 36 | Start a new trip whenever the gap between consecutive photos exceeds N hours. | | --include-home | off | Also show trips whose centroid is within 30 km of your detected home (hidden by default). | | --home lat,lon | — | Override the home location used to filter home-area trips. | | --no-geocode | geocode on | Skip the Nominatim place lookup (~1s/trip). Names fall back to bare date ranges. | | --dry-run | off | Walk, cluster, and create trips, but don't upload any photos. |

How it works

1. Walk + EXIF — recursively scans the folder, reads timestamp + GPS from each photo. OneDrive cloud-only placeholders are detected and skipped so the scan never triggers a download.
2. Cluster — sorts by capture time and splits into trips on gaps larger than --gap-hours. Trips near your home are hidden unless --include-home.
3. Name — every trip gets a date-range label; with geocoding on, a place name from the GPS centroid via Nominatim.
4. Preview — interactive review where you can rename, skip, or accept trips. Nothing is uploaded until you confirm.
5. Create trips + upload — creates the trips on ukung.com, then uploads each photo. A central SQLite ledger at ~/.ukung/import-ledger.db records every upload so re-runs skip work already done. The folder also gets a manifest so a re-run resumes the same plan instead of re-clustering.

Environment variables

| Var | Default | Purpose | |---|---|---| | UKUNG_API_BASE | https://ukung.com | Override the API host. Useful for local dev. | | UKUNG_CONFIG_PATH | ~/.ukung/config.json | Override where the token + account info are stored. | | UKUNG_LEDGER_PATH | ~/.ukung/import-ledger.db | Override the upload-ledger database path. |