Skip to content
credctl
Blog

Quickstart

Install credctl

Section titled “Install credctl”
Section titled “Homebrew (recommended)”
Terminal window
brew install credctl/tap/credctl

GitHub Releases

Section titled “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/credctl/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

Section titled “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. By default, Touch ID will also be required for all future signing operations (e.g., every time you run credctl auth).

If Touch ID is not available on your machine (e.g., Mac mini, clamshell mode), use credctl init --biometric=none to allow silent signing without user verification.

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 your cloud provider

Section titled “Set up your cloud provider”

Choose your cloud provider. You only need one to get started — each is a single command.

Option A: AWS

Section titled “Option A: AWS”
Terminal window
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

Replace the policy ARN with the IAM policy you want attached to the role. This single command handles everything: hosting OIDC documents on S3, creating the IAM OIDC provider and role, and configuring your AWS CLI profile.

Option B: GCP

Section titled “Option B: GCP”
Terminal window
credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com

This single command handles everything: hosting OIDC documents on GCS, creating the Workload Identity Pool and OIDC Provider, binding the service account, and generating the credential config file.

See the GCP setup guide for prerequisites and details.

Authenticate

Section titled “Authenticate”
Terminal window
credctl auth

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

Expected output (AWS):

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

Verify it works

Section titled “Verify it works”

AWS

Section titled “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"
}

Or use the AWS profile that setup aws configured automatically:

Terminal window
AWS_PROFILE=credctl aws s3 ls

GCP

Section titled “GCP”
Terminal window
export GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1
gcloud auth login --cred-file=~/.credctl/gcp-credentials.json
gcloud storage ls

Add a second cloud

Section titled “Add a second cloud”

If you set up one cloud and want to add another, just run the second setup command. It automatically reuses the OIDC issuer from your first cloud — no need to copy-paste URLs or think about where OIDC is hosted.

Terminal window
# If you started with AWS, add GCP:
credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com


# If you started with GCP, add AWS:
credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/MyDevPolicy

Reduce Touch ID prompts with the daemon (optional, experimental)

Section titled “Reduce Touch ID prompts with the daemon (optional, experimental)”

If you use multiple tools that need credentials (AWS CLI, Terraform, IDE), each triggers its own Touch ID prompt. The credential daemon caches credentials after the first prompt and serves them instantly to subsequent callers.

Terminal window
# Start the daemon (runs in the foreground for now)
credctl daemon start

With the daemon running, credctl auth returns cached credentials without Touch ID until they expire (~1 hour for AWS). No configuration changes needed — credctl auth detects the daemon automatically.

See credctl daemon for details and current limitations.

What’s next

Section titled “What’s next”