Skip to content
credctl

Quickstart

Install credctl

Terminal window
brew install matzhouse/tap/credctl

GitHub Releases

Download the latest signed .app bundle from GitHub Releases and extract it:

Terminal window
# Download the latest release (replace VERSION with the actual version)
curl -L https://github.com/matzhouse/credctl/releases/download/VERSION/credctl-darwin-arm64.tar.gz -o credctl.tar.gz
tar xzf credctl.tar.gz
sudo mv credctl.app /Applications/

Add the binary to your PATH:

Terminal window
echo 'export PATH="/Applications/credctl.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify the installation:

Terminal window
credctl version

Expected output:

credctl v0.1.0 (commit: abc1234)

Generate your device identity

Terminal window
credctl init

Touch ID prompts you to authorise key creation. The Secure Enclave generates an ECDSA P-256 key pair — the private key never leaves the hardware.

Expected output:

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.

Set up AWS infrastructure

This single command deploys everything credctl needs — an S3 bucket, CloudFront distribution, IAM OIDC provider, and IAM role — via CloudFormation:

Terminal window
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

Replace arn:aws:iam::123456789012:policy/MyDevPolicy with the ARN of the IAM policy you want attached to the role. This policy controls what AWS resources credctl can access.

The command also generates and publishes OIDC discovery documents automatically.

Expected output:

Deploying CloudFormation stack 'credctl-infra' in us-east-1...
Waiting for stack to complete...


Stack outputs:
  Issuer URL: https://d1234567890.cloudfront.net
  Role ARN:   arn:aws:iam::123456789012:role/credctl-device-role
  S3 Bucket:  credctl-oidc-123456789012


Generating OIDC documents...
Publishing OIDC documents...
AWS setup complete. Configure your AWS CLI:
  echo '[profile credctl]\ncredential_process = credctl auth' >> ~/.aws/config

Authenticate

Terminal window
credctl auth

credctl signs a JWT with your Secure Enclave key and exchanges it for short-lived AWS STS credentials via AssumeRoleWithWebIdentity. Touch ID prompts you to authorise the signing operation.

Expected output:

{
  "Version": 1,
  "AccessKeyId": "ASIAI...",
  "SecretAccessKey": "...",
  "SessionToken": "...",
  "Expiration": "2026-03-04T12:30:00Z"
}

Verify it works

Use the credentials to call AWS:

Terminal window
eval $(credctl auth --format env)
aws sts get-caller-identity

Expected output:

{
  "UserId": "AROAI...:credctl-aBcDeFg1",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/credctl-device-role/credctl-aBcDeFg1"
}

You have a working hardware-bound credential. No plaintext keys on disk.

Set up the credential helper (optional)

For transparent integration with the AWS CLI and SDKs, add a credential_process entry to ~/.aws/config:

[profile credctl]
credential_process = credctl auth

Now any tool that uses AWS profiles works automatically:

Terminal window
AWS_PROFILE=credctl aws s3 ls

What’s next