macOS Only

Authsia CLI

Your vault in the terminal, with guardrails for agentic AI workflows

Back to Authsia

Getting Started

Prerequisites

  • macOS 13 or later
  • Authsia app installed and running
  • CLI access enabled: Authsia → Settings → Security → CLI Access

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:
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)

Protecting secrets in agentic AI workflows

  • Prefer authsia:// references over pasting real secrets into prompts, config files, or generated code.
  • Use authsia exec for agent-run commands so secrets are injected into the target process instead of lingering in your shell history.
  • Use per-item CLI permissions for anything an agent should never be allowed to read, even on your local machine.

Common Workflows

Workflow Command
Copy TOTP code authsia code github --copy
Get a password authsia get password "AWS Console"
Load SSH keys authsia load ssh
Run with secrets authsia exec --env-file .env -- npm start
Read a secret reference authsia read "authsia://password/GitHub/password"
Scan dotfiles for secrets authsia scrape --dry-run
Start a session authsia unlock

Command Reference

All commands require the Authsia app to be running.

OTP Commands

Command Description
authsia code <query> Generate TOTP code
authsia get otp <query> Get OTP via get subcommand
authsia list accounts List all TOTP accounts (no secrets)
authsia export accounts Export all accounts as JSON

Password Commands

Command Description
authsia list passwords List all passwords (no secrets)
authsia get password <query> Get password fields
authsia add password Create a password item
authsia edit password <query> Update a password
authsia delete password <query> Delete a password

Certificate Commands

Command Description
authsia list certs List all certificates
authsia get cert <query> Get certificate fields
authsia add cert Add a certificate
authsia edit cert <query> Update a certificate
authsia delete cert <query> Delete a certificate

Secure Notes

Command Description
authsia list notes List all notes
authsia get note <query> Get note content
authsia add note Create a note
authsia edit note <query> Update a note
authsia delete note <query> Delete a note

SSH Keys

Command Description
authsia list ssh List all SSH keys
authsia get ssh <query> Get SSH key details
authsia add ssh Add an SSH key
authsia edit ssh <query> Update SSH key
authsia delete ssh <query> Delete SSH key
authsia load ssh [<query>] Load key(s) into ssh-agent

Secret Injection & References

Use load to export secrets as shell variables for interactive sessions. Use exec to inject secrets into a single command with automatic output masking. Use read to resolve a secret reference URI directly. For agentic AI and automation, prefer exec plus authsia:// references so plaintext secrets stay out of prompts, checked-in files, and long-lived shells.

Secret Reference URIs

authsia://type/item[/field][?folder=path]

Reference any vault secret by URI. Works as an env var value, inside .env files, or directly with authsia read. All references are resolved via biometric approval — the URI itself contains no secret data.

authsia://password/GitHub/password authsia://cert/TLS/privateKey authsia://otp/GitHub/code authsia://ssh/deploy/publicKey
Command Description
authsia load <type> [<query>] Export secrets as shell variables
authsia exec [<type>] Run command with secrets injected & masked
authsia read <uri> Resolve a secret reference URI

Committable .env files

Store authsia:// references instead of plaintext secrets. Safe to commit — the file contains no secret data, which makes this pattern a much better fit for agent-generated scripts and shared repo automation.

# .env — safe to commit
DB_HOST=localhost
DB_PASS=authsia://password/Prod-DB/password
API_KEY=authsia://password/GitHub/password
TLS_KEY=authsia://cert/TLS/privateKey
# All references resolved before launch; secrets masked in output
authsia exec --env-file .env -- make deploy

load vs exec — Which to Use

load exec
Where secrets live Parent shell (persists until unset) Target process only
Stdout exposure Emits export KEY='value' No stdout; secrets masked in subprocess output
.env file support — --env-file .env
Best for Interactive sessions, multiple commands CI/CD, single commands, security-sensitive

Secret Scanning

Command Description
authsia scrape Scan and migrate hardcoded secrets; auto-rewrites .env files with authsia:// references
authsia scrape --revert <path> Revert a modified file
authsia scrape --revert-all Revert all files
authsia scrape --list-modified List files modified by scrape

By default, scrape scans .env files, ~/.zshrc, ~/.bashrc, ~/.ssh, and ~/.kube/config. Use --path to specify custom paths.

.env files are auto-rewritten

When scrape finds secrets in a .env file, it replaces each secret line with an authsia:// reference — safe to commit. A diff preview is shown before any changes are applied. The original file is backed up in your vault (one backup per file; re-running updates the backup).

# Before
API_KEY=sk-prod-abc123

# After (safe to commit)
# Migrated to Authsia - Original: API_KEY
API_KEY=authsia://password/API_KEY/password
# Run your app with secrets resolved at launch:
authsia exec --env-file .env -- npm start

Utilities

Command Description
authsia unlock Biometric auth once; establishes session for subsequent commands
authsia init zsh Install shell integration (required for --silent flag)
authsia audit verify Validate integrity of the audit log chain

Security Architecture

The CLI has zero direct Keychain access. All operations flow through the Authsia app, with tamper-evident audit logging for sensitive actions and agent-safe secret handling.

authsia CLI
No Keychain
entitlements
XPC Bridge
Mach IPC
validated
Authsia App
Code-signed
Policy check
Biometric
Touch ID
Face ID
Keychain
Encrypted
on-device

Browser Autofill

The Authsia Chrome extension brings your vault to the browser. When you focus on a login field, Authsia shows matching credentials from your vault in an inline menu. No cloud, no servers — all local.

macOS Google Chrome Authsia app running CLI Access enabled per item

Note: Passwords must have a Website URL and CLI Access enabled to appear in browser autofill.