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.

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.
--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.

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