Skip to content

GUIDE.md

Latest commit

 

History

History
269 lines (195 loc) · 7.43 KB

GUIDE.md

File metadata and controls

269 lines (195 loc) · 7.43 KB
Raw

Authy — Detailed Guide

Everything beyond the README quick start. Reference for authentication, commands, configuration, and agent integration.

Authentication Modes

Mode Use case How
Passphrase Human admin, interactive Prompted at runtime
Keyfile Automation, headless --keyfile or AUTHY_KEYFILE env var
Session token Agent access, scoped --token or AUTHY_TOKEN (requires keyfile too)

Session tokens are read-only — agents cannot store, remove, or modify secrets or policies.

Run-Only Mode

Run-only restricts agents to safe commands and blocks sensitive ones that expose secret values directly.

Safe vs Sensitive Commands

Command Classification Run-only allowed?
authy run Safe — injects into subprocess Yes
authy resolve Safe — writes to file/stdout Yes
authy list Safe — names only, no values Yes
authy get Sensitive — exposes value No (exit 4)
authy env Sensitive — exposes values No (exit 4)
authy export Sensitive — exposes values No (exit 4)

Run-only can be set at either level — either one triggers the restriction:

# Token-level
authy session create --scope my-scope --ttl 1h --run-only

# Policy-level
authy policy create agent-scope --allow "*" --run-only

# Toggle on existing policy
authy policy update agent-scope --run-only true

Non-Interactive Mode

When stdin is not a TTY (CI/CD, agent scripts), authy fails fast instead of prompting. Set credentials via environment:

export AUTHY_KEYFILE=~/.authy/keys/master.key
# or: export AUTHY_PASSPHRASE=...
# or: export AUTHY_TOKEN=... (with AUTHY_KEYFILE)

Set AUTHY_NON_INTERACTIVE=1 to force non-interactive mode even with a TTY.

Commands

Secrets

authy store <name>                # reads value from stdin, Ctrl+D to finish
authy get <name>                  # output value to stdout
authy list [--scope <s>] [--json] # list secret names
authy remove <name>               # delete a secret
authy rotate <name>               # update value, bumps version

Environment Variable Output

Output secrets as environment variables in different formats:

# Shell format (sourceable)
eval "$(authy env --scope agent --format shell --uppercase --replace-dash '_')"

# Dotenv format
authy env --scope agent --format dotenv > .env

# JSON format
authy env --scope agent --format json | jq .

Options:

  • --format shell|dotenv|json — output format (default: shell)
  • --uppercase — transform names to UPPER_CASE
  • --replace-dash <char> — replace - in names (e.g., _)
  • --no-export — omit export prefix in shell format

Import / Export

# Import from .env files
authy import .env                 # transforms UPPER_SNAKE to lower-kebab
authy import .env --keep-names    # preserve original names
authy import .env --force         # overwrite existing secrets
authy import .env --prefix api    # prefix all names with "api-"
authy import .env --dry-run       # preview without writing
authy import -                    # read from stdin

# Export
authy export --format env [--scope <s>]
authy export --format json

Policies

authy policy create <name> --allow "db-*" --deny "prod-*"
authy policy create <name> --allow "*" --run-only
authy policy show <name>
authy policy update <name> --run-only true
authy policy list [--json]
authy policy remove <name>
authy policy test --scope <s> <name>   # test if scope can access a secret

Policy evaluation: deny overrides allow, default deny.

Sessions

authy session create --scope <policy> --ttl <duration> [--run-only]
authy session list [--json]
authy session revoke <id>
authy session revoke-all

Token format: authy_v1.<base64> — scannable prefix for leak detection.

Subprocess Injection

authy run [--scope <s>] [--uppercase] [--replace-dash <c>] -- <command> [args...]

Secrets matching the scope are injected as environment variables into the child process. The parent process (agent) never sees them.

File Placeholder Resolution

authy resolve <file> [--scope <s>] [--output <path>]

Replaces <authy:key-name> placeholders in a file with secret values. Safe for run-only mode — the resolved output goes to a file or stdout, never returned as a raw value.

# Resolve config template to stdout
authy resolve config.yaml.tpl --scope deploy

# Resolve to a file
authy resolve config.yaml.tpl --scope deploy --output config.yaml

Rekey (Change Credentials)

authy rekey [--generate-keyfile <path>] [--new-keyfile <path>] [--to-passphrase]

Re-encrypts the vault with new credentials. Requires master key authentication (tokens cannot rekey). All existing session tokens are invalidated after rekey.

# Switch from passphrase to keyfile
authy rekey --generate-keyfile ~/.authy/keys/new.key

# Switch to an existing keyfile
authy rekey --new-keyfile ~/.authy/keys/other.key

# Switch from keyfile to passphrase
authy rekey --to-passphrase

Audit

authy audit show [--json]         # show log entries
authy audit verify                # verify HMAC chain integrity
authy audit export                # export as JSON

Project Config

authy project-info                # show .authy.toml config
authy alias [scope] [tools...]    # generate shell aliases
authy hook <shell>                # output shell hook code

Admin

authy admin [--keyfile <path>]    # launch TUI
authy config show                 # show configuration

Project Config (.authy.toml)

Auto-discovered from current directory upward. Makes --scope optional on run, env, export:

[authy]
scope = "my-project"
keyfile = "~/.authy/keys/master.key"
uppercase = true
replace_dash = "_"
aliases = ["claude", "aider"]     # tools to generate aliases for

Shell Hook

Auto-activate project config on cd (like direnv):

eval "$(authy hook bash)"    # add to ~/.bashrc
eval "$(authy hook zsh)"     # add to ~/.zshrc
authy hook fish | source     # add to ~/.config/fish/config.fish

Shell Aliases

Generate aliases that wrap tools with authy run:

authy alias --from-project        # uses .authy.toml aliases list
authy alias my-scope claude aider # explicit scope and tools

File Layout

~/.authy/
  vault.age           Encrypted vault (secrets + policies + sessions)
  audit.log           Append-only audit log (JSONL)
  authy.toml          Configuration (optional)
  keys/
    master.key        age identity (private key)

Exit Codes

Code Meaning
0 Success
1 General error
2 Authentication failed
3 Not found (secret, policy, session)
4 Access denied / run-only restriction
5 Vault error (corrupt, missing)
6 Token invalid, expired, or revoked
7 Subprocess error

JSON Output

All read commands support --json. Errors with --json emit to stderr:

{"error": {"code": "access_denied", "message": "Run-only mode", "exit_code": 4}}

Agent Skills

Install the skill for AI coding agents:

npx skills add eric8810/authy          # Agent Skills standard
clawhub install eric8810/authy         # ClawHub
cp -r skills/authy ~/.claude/skills/   # Manual (Claude Code)

The skill teaches agents only authy run and authy list — agents never learn commands that expose values.