Getting Started

Auths gives you a permanent, device-bound cryptographic identity. Everything below runs locally — no account, no server, no keys ever leaving your device.

In this guide, you will generate your identity, link it to your GitHub account, and sign and verify your first artifact.

1. Install the CLI

The auths CLI is your local control plane. It manages your keys, handles signing, and configures Git.

brew install auths-dev/auths-cli/auths
# or via shell script
curl -fsSL https://get.auths.dev | sh
# or via Cargo
cargo install auths-cli

Want proof it works before any setup? Run the 30-second demo — it signs and verifies a throwaway artifact entirely offline:

auths demo

2. Create Your Identity

Next, generate your permanent root identity.

auths init

This does a few things:

  • Creates a P-256 keypair, hardware-backed where your platform supports it (Secure Enclave on macOS)
  • Establishes your KERI identity (did:keri:...) locally on your machine
  • Configures Git so your commits are signed automatically

Note: Your identity is generated completely offline. No private keys ever leave your device. Publishing your identity to a registry is strictly opt-in.

3. Link Your GitHub Account

To bind your identity to an existing platform account, add a platform claim:

auths id claim github

This walks you through a GitHub OAuth device flow — no SSH key juggling.

4. Sign & Verify an Artifact

Let's sign a file and verify the signature, end to end:

# 1. Create a dummy file
echo "Hello, Auths" > hello.txt


# 2. Sign it with your local device key
auths artifact sign hello.txt --sig-output hello.auths.json


# 3. Verify it — works offline, anyone with the file + signature can do this
auths artifact verify hello.txt

Want a public record? Add --log sigstore-rekor to the sign command and the signature lands on Sigstore's transparency log — the same ledger Google and GitHub use.

A hosted public registry for publishing and discovering signed artifacts is coming soon. auths artifact publish already works against any self-hosted registry via --registry <url>.

5. Set Up CI Signing

Add signing to your release workflow — no secrets needed:

- uses: auths-dev/sign@v1
  with:
    auths-version: '0.1.2'
    files: 'dist/*.tar.gz'

And commit verification to your CI. Export an identity bundle once and commit it — it carries your identity and authorization chain, so the runner verifies statelessly:

auths id export-bundle --alias main --output .auths/ci-bundle.json --max-age-secs 31536000
- uses: auths-dev/verify@v1
  with:
    auths-version: '0.1.2'
    identity-bundle: .auths/ci-bundle.json

Next Steps