Primary Commands¶
Primary¶
auths init¶
Set up your cryptographic identity and Git signing
| Flag | Default | Description |
|---|---|---|
--interactive |
— | Force interactive prompts (errors if not a TTY) |
--non-interactive |
— | Skip interactive prompts and use sensible defaults |
--profile <PROFILE> |
— | Preset profile: developer, ci, or agent |
--key-alias <KEY_ALIAS> |
main |
Key alias for the identity key (default: main) |
--force |
— | Force overwrite if identity already exists |
--dry-run |
— | Preview agent configuration without creating files or identities |
--registry <REGISTRY> |
https://auths-registry.fly.dev |
Registry URL for identity registration |
--register |
— | Register identity with the Auths Registry after creation |
--github-action |
— | Scaffold a GitHub Actions workflow using the auths attest-action |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths sign¶
Sign a Git commit or artifact file.
| Flag | Default | Description |
|---|---|---|
<TARGET> |
— | Commit ref, range, or artifact file path |
--sig-output <PATH> |
— | Output path for the signature file. Defaults to |
--key <KEY> |
— | Local alias of the identity key (for artifact signing) |
--device-key <DEVICE_KEY> |
— | Local alias of the device key (for artifact signing, required for files) |
--expires-in <N> |
— | Duration in seconds until expiration (per RFC 6749) |
--note <NOTE> |
— | Optional note to embed in the attestation (for artifact signing) |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths verify¶
Verify a signed commit or attestation.
| Flag | Default | Description |
|---|---|---|
--allowed-signers <ALLOWED_SIGNERS> |
.auths/allowed_signers |
Path to allowed signers file (commit verification) |
--identity-bundle <IDENTITY_BUNDLE> |
— | Path to identity bundle JSON (for CI/CD stateless commit verification) |
--issuer-pk <ISSUER_PK> |
— | Issuer public key in hex format (attestation verification) |
--issuer-did <ISSUER_DID> |
— | Issuer identity ID for attestation trust-based key resolution [aliases: --issuer] |
--witness-receipts <WITNESS_RECEIPTS> |
— | Path to witness receipts JSON file |
--witness-threshold <WITNESS_THRESHOLD> |
1 |
Witness quorum threshold |
--witness-keys <WITNESS_KEYS>... |
— | Witness public keys as DID:hex pairs |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths status¶
Show identity and agent status overview
| Flag | Default | Description |
|---|---|---|
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths whoami¶
Show the current identity on this machine
| Flag | Default | Description |
|---|---|---|
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
Setup & Troubleshooting¶
auths pair¶
Link devices to your identity
| Flag | Default | Description |
|---|---|---|
--join <CODE> |
— | Join an existing pairing session using a short code |
--registry <URL> |
— | Registry URL for pairing relay (omit for LAN mode) |
--timeout <SECONDS> |
300 |
Custom timeout in seconds for the pairing session (default: 300 = 5 minutes) [aliases: --expiry] |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths doctor¶
Run comprehensive health checks
| Flag | Default | Description |
|---|---|---|
--fix |
— | Auto-fix issues where possible |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths tutorial¶
Interactive tutorial for learning Auths concepts
| Flag | Default | Description |
|---|---|---|
-s, --skip <SECTION> |
— | Skip to a specific section (1-6) |
--reset |
— | Reset progress and start from the beginning |
--list |
— | List all tutorial sections |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
Utilities¶
auths config set¶
Set a configuration value (e.g. auths config set passphrase.cache always)
| Flag | Default | Description |
|---|---|---|
<KEY> |
— | Dotted key path (e.g. passphrase.cache, passphrase.duration) |
<VALUE> |
— | Value to assign |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths config get¶
Get a configuration value (e.g. auths config get passphrase.cache)
| Flag | Default | Description |
|---|---|---|
<KEY> |
— | Dotted key path |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths config show¶
Show the full configuration
| Flag | Default | Description |
|---|---|---|
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |
auths completions¶
Generate shell completions
| Flag | Default | Description |
|---|---|---|
<SHELL> |
— | The shell to generate completions for |
-j, --json |
— | Emit machine-readable JSON |
-q, --quiet |
— | Suppress non-essential output |
--repo <REPO> |
— | Override the local storage directory (default: ~/.auths) |