Rollback snapshot
A snapshot is created immediately before the operation. If it fails, no import changes are applied.
KeyHarbor documentation
Import licenses safely
Create a preview from installed apps or existing records, review every change, and apply the import only when it looks right.
Verified with KeyHarbor 1.6.2 · July 13, 2026
Nothing is saved before you review it
KeyHarbor analyzes the selected source and builds a preview first. The preview separates new records, possible updates, unchanged records, duplicates, and skipped rows so you can decide what should be applied.
Immediately before applying an import or restore, KeyHarbor creates a rollback snapshot. If the snapshot cannot be created, the operation stops without changing the current data.
The screenshots in this guide use public-safe demo values. Installed app imports do not store the app's absolute file path in a license record.
Open the Import Wizard
Start from the location that matches what you are importing.
- 1Choose Import Existing Licenses on an empty library.
- 2Choose File > Import... from the menu bar.
- 3Open Settings > Storage > Restore and select an import action.
| Goal | Use | What it brings in |
|---|---|---|
| Move all KeyHarbor data | Encrypted .khbackup | Licenses, attachments, icons, receipts, categories, smart folders, and payment sources |
| Move spreadsheet records | CSV, TSV, or delimited text | The license fields you explicitly map |
| Create drafts from this Mac | Installed Apps | App name, publisher, version, bundle identifier hint, and icon |
| Create Homebrew drafts | Homebrew Cask or Brewfile | Cask names and available installation metadata |
| Move structured records | JSON or ZIP | License data and any assets supported by the selected format |
Installed Apps creates drafts, not finished licenses
KeyHarbor scans applications on the Mac and uses available bundle metadata as the starting point for a license record.
Added from app metadata
- App name
- Publisher
- Version
- Bundle identifier hint
- App icon
Review or enter yourself
- Product key
- Owner or purchase email
- License type and billing cycle
- Purchase and expiry dates
- Price and currency
- Website, download URL, and notes
A macOS app bundle normally does not contain your product key, purchase account, price, or expiry date. Leave unknown fields empty instead of inventing values.
1. Select apps
Search by app name or publisher, then select only the apps you want to turn into license drafts.
- Clear the search field if an app is missing.
- Open Scan Notices to see excluded system apps, unreadable Info.plist files, or duplicate bundle identifiers.
- Continue with only the apps you intend to organize.
2. Complete license details
Select each app on the left and add only the purchase and license information you know. Every field is optional and remains editable after import.
- Confirm the detected app name, publisher, version, and icon.
- Enter the product key and purchase email only when they are known.
- Set subscription, billing, date, and price details when they apply.
3. Review and import
Check whether each row is new, a possible match, or unchanged. Confirm icon readiness and rollback protection before applying the import.
- Review the counts for new, matching, and unchanged licenses.
- Inspect possible matches before choosing a merge policy.
- Apply only after the rollback snapshot notice is present.
Understand the preview states
The preview does not expose full product keys and does not write to the library until you confirm the operation.
| State | Meaning |
|---|---|
| New | A license that will be added as a new record. |
| Changed | A possible existing match with one or more different fields. |
| Same | The incoming values match the current record, so no change is needed. |
| Duplicate | A repeated identifier or name conflicts with another row or existing record. |
| Skipped | A row you excluded or a row that cannot be applied because of an error. |
Choose a merge decision only for real matches
Merge options appear only when an incoming row matches an existing license candidate.
| Decision | Behavior | Use when |
|---|---|---|
| Fill empty fields | Keeps existing values and fills only blank fields. | You want the safest default or are unsure which source is newer. |
| Keep existing values | Preserves conflicting values already in KeyHarbor. | The current KeyHarbor record is more accurate. |
| Use imported values | Updates the changed fields shown in the preview. | The imported source is the newer source of truth. |
| Keep both | Preserves the existing license and adds the imported row separately. | The records share a name but represent different purchases or licenses. |
When you are unsure, start with Fill empty fields and inspect the field-level changes before applying the import.
Check the result instead of assuming full success
The completion screen reports each outcome separately. Open the imported items and compare the result with the preview before continuing with more data.
ImportedUpdatedExisting keptBoth keptUser skippedDuplicate skippedError skippedWarnings
Automatic backup and rollback
KeyHarbor protects the current library before an import or restore changes it.
Restore the last snapshot
Open Settings > Storage > Restore > Restore Last Rollback Snapshot, verify its timestamp, and then confirm the restore.
Merge is not restore
Merge keeps the current library and adds or updates selected records. Restore replaces the current store with the backup state.
An encrypted .khbackup uses the separate backup password chosen when the file was created. It is not automatically the same as the KeyHarbor master password.
Common warnings and fixes
An installed app is missing
Clear the search field and expand Scan Notices. System apps, unreadable Info.plist files, and duplicate bundle identifiers may be excluded.
The product key is empty
This is expected. App bundles usually do not include product keys or purchase email. Enter the value in step 2 or edit the license later.
Merge options are not visible
All selected rows are new and have no existing match. Merge options appear only for matching candidates.
A CSV column is mapped incorrectly
Open the field mapping menu and select the correct KeyHarbor field. A mapped Name field is required to continue.
The import appears to stop
Look for a backup password, CSV mapping, or duplicate decision dialog behind another window. Cancel and retry with a smaller copy of the source if needed.
The result is not what you expected
Review the imported, updated, and skipped counts. Restore the last rollback snapshot when the changes are not acceptable.
Security and privacy notes
- Use encrypted .khbackup when moving the complete KeyHarbor state between Macs.
- Unencrypted ZIP, CSV, JSON, and preserved notes can contain sensitive data; keep the source files in a secure location.
- Product keys are masked in the preview, but the original import file still requires protection.
- Installed app imports do not save the app's absolute path in the license record.