Authsia CLI

Installation

# The CLI is bundled with the app automatically.
# Symlink it to your PATH:
ln -sf /Applications/Authsia.app/Contents/Helpers/authsia ~/.local/bin/authsia

# Or add to your PATH in ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"

# Enable shell integration:
eval "$(authsia init zsh)"

Quick Start

1. 1

   Open Authsia app, go to Settings → Security → Enable CLI Access

2. 2

   Run authsia unlock — enter biometric to start a session

   $ authsia unlock
   Touch ID prompt will appear in Authsia app...
   Session started. Valid for 8 hours.

3. 3

   Run authsia list accounts — verify the connection works

   $ authsia list accounts
   github        GitHub
   aws-console   Amazon Web Services
   ms-365        Microsoft 365

4. 4

   Run authsia code github --copy — your first TOTP code, copied to clipboard

   $ authsia code github --copy
   482 391  (copied to clipboard, valid for 18s)

The Problem

AI coding agents observe everything in your terminal session: environment variables, command output, file contents, and shell history. Any plaintext secret that appears in any of these surfaces is captured by the agent's context window and may be sent to a remote API.

The Pattern: References Until the Last Mile

Use authsia:// URIs everywhere a secret would go. These references contain no secret data — they're safe to display, commit, and share with agents. Secrets are only resolved at the final approved authsia exec launch.

# .env — agent can read/write this freely, no secrets
DB_HOST=localhost
DB_PASS=authsia://password/Prod-DB/password
API_KEY=authsia://password/GitHub/password

# Resolve all references at launch; mask secrets in output
$ authsia exec --env-file .env -- npm start
> Server listening on :3000
> Connected to DB with password <concealed by authsia>

In the intended exec flow, the agent sees the reference URIs and masked text output, not the plaintext secret values.

Project Setup

Add rules to your project so the agent uses authsia:// references by default and never inlines plaintext secrets.

Codex AGENTS.md

## Secret Management
- Never inline plaintext secrets in code, env files, shell commands, logs, or final answers.
- Use authsia:// reference URIs for secret values:
  - authsia://password/<name>/password
  - authsia://cert/<name>/privateKey
  - authsia://note/<name>/content
- Run commands that need secrets through:
  - authsia exec --env-file .env -- <command>
- For background runs, use scoped credentials with --allow exec, plus ssh only when Git/SSH signing is required.
- Keep masking enabled. Never use --no-masking in agentic sessions.
- Do not use authsia get/load/read/inject to expose plaintext secrets to the agent context.
- List non-secret item names with: authsia list passwords --format table

Claude Code CLAUDE.md

# Secret Management
# - NEVER inline plaintext secrets in code, env files, or shell commands.
# - Use authsia:// reference URIs for all secret values:
#     authsia://password/<name>/password
#     authsia://cert/<name>/privateKey
#     authsia://note/<name>/content
# - Run commands that need secrets via:
#     authsia exec --env-file .env -- <command>
# - Only run trusted commands under authsia exec; that child process receives the secret.
# - Keep masking enabled. Never use --no-masking in agent sessions.
# - Grant automation credentials only exec, plus ssh when Git/SSH signing is needed.
# - NEVER grant load, read, get, or inject to AI agents.
# - NEVER run: export SECRET=..., echo $SECRET, or cat credentials.
# - Available secrets: authsia list passwords --format table

Cursor .cursor/rules

# Secret Management
# Never inline plaintext secrets. Use authsia:// URIs:
#   authsia://password/<name>/password
# Run: authsia exec --env-file .env -- <command>
# Keep masking enabled. Do not grant load/read/get/inject to agents.
# List: authsia list passwords --format table

Windsurf .windsurfrules / GitHub Copilot .github/copilot-instructions.md

# Secret Management
# Never hardcode secrets. Reference them via authsia:// URIs.
# Pattern: authsia://password/<name>/password
# Execute trusted commands with masking: authsia exec --env-file .env -- <command>
# Do not grant load/read/get/inject to AI agents.

Scoped Automation Credentials

For background agents, CI runners, or editor integrations that need secrets without interactive biometric approval, create a scoped automation credential. Each credential is folder-bound, TTL-limited, revocable, and grants only the capabilities listed in --allow.

# Create a 15-minute credential scoped to the Team/API folder
$ authsia access create --name claude-code --scope Team/API --ttl 15m --allow exec,ssh
Created credential 8D6A3B75-... (expires in 15m, scope: Team/API, allow: exec,ssh)

# Set the env var so Authsia CLI and SSH agent can validate this session
$ export AUTHSIA_ACCESS_CREDENTIAL=8D6A3B75-...

# Agent can now resolve secrets within scope — no biometric prompt
$ authsia exec --env-file .env -- npm test

# Agent can also use scoped SSH keys for Git
$ authsia exec -- git push

# Review active credentials
$ authsia access list --format table

# Revoke early if no longer needed
$ authsia access revoke 8D6A3B75-...

A normal CLI unlock does not automatically approve SSH signing. The built-in Authsia SSH agent checks for an active local credential with the ssh capability, a matching folder scope, a CLI-enabled SSH key, and any configured host binding before it signs. Without an automation credential, session-based SSH approval prompts through the app and caches per key for the same configured CLI session TTL.

Quick Reference by Tool

Recommended patterns for popular AI coding tools. All follow the same principle: references in, trusted exec at the boundary.