credctl init

Synopsis

credctl init [flags]

Description

credctl init generates a hardware-bound ECDSA P-256 key pair in the macOS Secure Enclave and writes the initial configuration to ~/.credctl/. The private key never leaves the Secure Enclave hardware. The public key is exported as a PEM file to ~/.credctl/device.pub.

Touch ID prompts you to authorise key creation. By default, Touch ID is also required for all future signing operations (e.g., credctl auth). Use the --biometric flag to control this behaviour.

This command creates:

• ~/.credctl/config.json — device identity configuration (0600 permissions)
• ~/.credctl/device.pub — public key in PEM format (0644 permissions)

Flags

Flag	Type	Default	Description
--force	boolean	false	Delete existing key and reinitialise. The old key is permanently destroyed.
--biometric	string	any	Biometric policy for signing operations. any — Touch ID with passcode fallback (kSecAccessControlUserPresence). fingerprint — Touch ID only, no passcode fallback; key is invalidated if fingerprints change (kSecAccessControlBiometryCurrentSet). none — no user verification; signing happens silently when the device is unlocked.
--key-tag	string	com.crzy.credctl.device-key	Override the Keychain application tag for the Secure Enclave key.

Examples

Basic initialisation

credctl init

Generating Secure Enclave key pair...

✓ Device identity created (Secure Enclave)
  Fingerprint: SHA256:aBcDeFg...
  Public key:  ~/.credctl/device.pub

  Next: Register this public key with your cloud provider or credctl broker.

Force reinitialisation

If you need to replace an existing device identity:

credctl init --force

Deleting existing key...
Generating Secure Enclave key pair...

✓ Device identity created (Secure Enclave)
  Fingerprint: SHA256:xYzAbCd...
  Public key:  ~/.credctl/device.pub

  Next: Register this public key with your cloud provider or credctl broker.

Caution

--force permanently destroys the existing Secure Enclave key. Any cloud provider configurations that reference the old key will stop working. You will need to run credctl setup aws again.

Disable Touch ID (headless or clamshell environments)

For Mac minis, CI runners, or laptops in clamshell mode where Touch ID is not available:

credctl init --biometric=none

Biometric policy is permanent

The --biometric policy is set at key creation time and baked into the Secure Enclave access control. It cannot be changed after the key is created. To change the biometric policy, you must reinitialise with credctl init --force --biometric=<new-policy>, which destroys and recreates the key.

Exit codes

Code	Meaning
0	Device identity created successfully
1	Error (Secure Enclave not available, permission failure, or other error)

See also

• credctl status — check device identity health
• credctl setup aws — set up AWS infrastructure after initialisation
• Configuration reference — ~/.credctl/config.json schema