Profiles¶

Auths supports three setup profiles for different environments: developer, CI, and agent. Each profile creates a distinct type of identity optimized for its use case. Organizations can layer on top of any individual identity.

Setup profiles¶

The auths init command offers an interactive profile selector, or you can specify one directly:

auths init --profile developer
auths init --profile ci
auths init --profile agent

Developer profile¶

The default for local development. Creates a full identity with platform keychain integration, device linking, and Git signing configuration.

auths init
# or explicitly:
auths init --profile developer

What it does:

Verifies keychain access (macOS Keychain, Linux Secret Service, Windows Credential Manager, or encrypted file fallback)
Checks Git version compatibility
Prompts for a key name (default: main)
Generates a P-256 keypair (the default; Ed25519 available) with KERI pre-rotation
Configures Git signing (gpg.format, gpg.ssh.program, user.signingKey, commit.gpgSign)
Installs the commit-trailer hook (core.hooksPath → ~/.auths/githooks/) so plain git commit is verifiable
Optionally links your GitHub account for identity verification
Optionally (--register) publishes the identity to a registry — never automatic

Interactive prompts include:

Key name -- the local name for your signing key
Conflict policy -- reuse an existing identity or create a new one
Git scope -- configure signing for this repository only (--local) or all repositories (--global)
Platform verification -- link your GitHub account for identity discovery

For non-interactive use:

auths init --profile developer --non-interactive --key-alias my-key

Flag	Default	Description
`--key-alias`	`main`	Alias for the identity key
`--force`	`false`	Overwrite existing identity
`--non-interactive`	`false`	Skip all prompts, use defaults
`--registry`	`https://registry.auths.dev`	Registry URL for identity registration (registry not yet live)
`--register`	`false`	Register identity with the Auths Registry

CI profile¶

Creates an identity for CI/CD pipelines backed by an encrypted key file, and prints a copy-pasteable env block for your CI secrets.

auths init --profile ci --non-interactive > auths-ci.env

What it does:

Detects the CI environment (GitHub Actions, GitLab CI, or custom)
Creates an identity with a file-backed keychain (.auths-ci/keys.enc in the working directory)
Installs the commit-trailer hook so CI commits are verifiable
Prints the env block to stdout (pipeable): keychain settings, AUTHS_REPO, the key alias, and GIT_CONFIG_* entries wiring up signing + the hook

The passphrase comes from AUTHS_PASSPHRASE if set (it must meet the strength policy — 12+ chars, 3 of 4 character classes — or init fails fast with AUTHS-E5008), falling back to a built-in CI default.

Run init and sign in the same job

The file-backed key lives where init put it. Initialize and sign within one CI job, or persist .auths-ci/ between steps.

Agent profile¶

An agent is not a standalone identity — it is a delegated identifier under your root identity, scoped and time-limited. The Agent profile routes you into that delegation flow.

auths init --profile agent

What it does (interactive, with an existing root identity):

Prompts for capability scope (e.g. sign_commit) as a checklist
Prompts for a label (also the keychain alias for the agent's key; default agent)
Delegates the agent: a new did:keri: whose delegation your root anchors in its key event log, carrying the selected capabilities and a default 1-year expiry

If no root identity exists yet, the wizard tells you to run auths init (developer) first. In --non-interactive mode the profile intentionally errors with guidance — scripted callers should use the explicit command instead:

auths id agent add --label deploy-bot --key main --scope sign_commit --expires-in 31536000

Use --dry-run to preview the configuration without creating anything:

auths init --profile agent --dry-run

Manage agents with auths id agent list, auths id agent rotate, and auths id agent revoke. Full guide: Agent Identities.

Organization identities¶

Organizations are separate identities that can authorize members with role-based capabilities.

Creating an organization¶

auths org init --name "my-org"

This creates a new did:keri identity for the organization, stored in its own Git repository. The creator receives an admin attestation with all capabilities:

SignCommit -- sign Git commits
SignRelease -- sign releases/tarballs
ManageMembers -- add or revoke members
RotateKeys -- perform key rotation

Optionally provide a custom key alias or additional metadata:

auths org init \
  --name "my-org" \
  --key org-myorg \
  --metadata-file org-metadata.json

Adding members¶

Admins (users with the ManageMembers capability) can add members:

auths org add-member \
  --org "did:keri:E..." \
  --member "did:keri:E..." \
  --role member

Role	Default capabilities
`admin`	`SignCommit`, `SignRelease`, `ManageMembers`, `RotateKeys`
`member`	`SignCommit`, `SignRelease`
`readonly`	(none)

Override default capabilities with --capabilities:

auths org add-member \
  --org "did:keri:E..." \
  --member "did:keri:E..." \
  --role member \
  --capabilities sign_commit

Revoking members¶

auths org revoke-member \
  --org "did:keri:E..." \
  --member "did:keri:E..." \
  --note "Access removed"

Listing members¶

auths org list-members --org "did:keri:E..."
auths org list-members --org "did:keri:E..." --include-revoked

Output shows a tree with role, delegation chain, and capabilities:

Members (3 total):
----
|- did:keri:Eabc... [admin]
|  |- did:keri:Edef... [member] [SignCommit, SignRelease]
|     delegated by: did:keri:Eabc...
|- did:keri:Eghi... [readonly]
----

When to use each profile¶

Scenario	Profile	Reason
Daily development on your laptop	Developer	Full keychain integration, Git signing, platform verification
GitHub Actions / GitLab CI pipeline	CI	Ephemeral, no persistent secrets needed on the runner
AI coding assistant (Copilot, Claude, etc.)	Agent	Scoped capabilities, automatic expiration
Team or company signing policy	Organization + Developer	Centralized member management with delegated signing

Managing multiple profiles¶

A single machine can host multiple identities. The active identity is determined by the ~/.auths repository (or the --repo flag).

Switching between identities¶

Use the --repo flag to point at a different identity repository:

# Use default identity
auths status

# Use org identity
auths status --repo ~/orgs/my-org/.auths

# Use a project-specific identity
auths status --repo /path/to/project/.auths

Environment variable overrides¶

Variable	Description
`AUTHS_HOME`	Override the default `~/.auths` identity repository path
`AUTHS_KEYCHAIN_BACKEND`	Override the keychain backend (`file`, `memory`)
`AUTHS_KEYCHAIN_FILE`	Path for the encrypted file keychain
`AUTHS_PASSPHRASE`	Passphrase for the file keychain backend

Per-repository Git signing¶

During auths init, choose "This repository only" at the Git scope prompt to configure signing for a single repository. This writes to .git/config instead of ~/.gitconfig, allowing different identities per project:

# In project A (uses identity A)
cd ~/projects/project-a
auths init --profile developer
# Select: "This repository only"

# In project B (uses identity B)
cd ~/projects/project-b
auths init --profile developer --repo ~/alt-identity/.auths
# Select: "This repository only"

Checking the active identity¶

auths status

Output shows the identity DID, agent status, and linked device count:

Identity:   did:keri:EnXNx...
Agent:      stopped
Devices:    2 linked