Identity & Recovery

Your identity and device keys

Merka separates “you” from “this device”:

• Your user identity is your long-lived Merka identity. It is recoverable from your recovery file.
• Your device key is unique to one Mac, phone, browser, or TUI install. It proves that this device is trusted when it talks to your Merka system.

When you first run merka, a cryptographic signing key is generated for your device. This device key is:

• Unique to this device — No other device shares it.
• Stored securely — On macOS it lives in the login Keychain; on Linux it uses the secret service (or an encrypted file fallback).
• Protected by biometrics — On macOS, subsequent launches require Touch ID (or your system password on Macs without Touch ID) before the key is read. On first run, the key is generated without a prompt.
• Identified by a fingerprint — A short hex string like fp:0xA3B4 C5D6 E7F8 9012 that you can use to verify your device.

Your device key proves “this is my device” to your Merka system. It is created automatically on first launch — you don’t need to set up accounts or passwords.

Normal device enrollment uses an existing trusted device to approve the new one and hand off the user identity capability. The recovery file is reserved for the case where no trusted device is available.

The recovery file

During first launch, merka generates a .merka-recovery file and saves it to:

~/.local/share/rocks.cosmic.merka.cli/recovery/merka-recovery.json                # Linux
~/Library/Application Support/rocks.cosmic.merka.cli/recovery/merka-recovery.json  # macOS

This file is the only way to recover your identity if you lose all trusted devices. It contains a high-entropy recovery key that can reconstruct your user identity on a new device. If you enabled the optional recovery passphrase, the file alone is not enough; you also need that passphrase.

What to do with it

Save it somewhere safe. Good options:

• A USB drive you keep in a drawer
• Your password manager (1Password, Bitwarden, etc.)
• A printed copy in a safe place

What happens if you lose it

If you lose all trusted devices and the recovery file, your identity is gone. You can create a new identity, but you’ll need to re-claim your system. This is intentional — your data stays yours, and nobody (including us) can recover it without the recovery file.

What’s inside the file

The file is a JSON document containing your recovery key and metadata. The recovery key itself is normally never shown on screen — it’s embedded in the file. You don’t need to memorize anything or write down codes.

Linking to cosmic.rocks

You can optionally link your device to a cosmic.rocks account. This enables:

• Cloud backup storage locations
• Multi-device sync
• Managed subscription features

To link, press [L] on the first-run screen or use:

merka identity link

Linking is optional. merka works fully standalone without a cosmic.rocks account.

Managing your identity

View your identity

merka identity show

Shows your device ID, fingerprint, tier, and link state. Add --json for machine-readable output.

List devices

merka identity devices

Lists all devices registered under your identity.

Unlink from cosmic.rocks

merka identity unlink

Removes the cosmic.rocks account link. Your local identity and data are unaffected.

Recovery

If you lose all trusted devices but have the recovery file, open it and copy the recovery_key value (a string starting with MK-), then run:

merka recover

You’ll be prompted for the recovery key. (You can also pass it directly with --recovery-key MK-..., or add --dry-run to validate the key without recovering.)

This restores your identity on the new device. You’ll then be able to re-connect to your existing Merka system.