Back to Authsia

Authsia CLI, without the wall of text

Start here for the commands developers actually use: install, setup, workspace refs, guarded terminal, agent JIT, SSH, and audit.

Install Workspace Guarded Agent JIT

quick path

# install app + CLI
brew install --cask james-liang-cs/authsia/authsia

# prepare the repo
authsia workspace init
authsia workspace status

# run commands through Authsia
authsia workspace run -- npm test
authsia guard

Install and check readiness

Use Homebrew for the released app and CLI. Existing DMG installs can be adopted without reinstalling.

Workspace workflow

Workspace commands keep repo config commit-safe. Vault item tags travel with their items, while each developer selects one local environment or the Default environment.

Select one environment

Named environments include default-environment items. Clearing the selection returns to Default-environment resolution.

Override one run

A one-run choice does not change the environment saved for this workspace.

How workspace, env-file, and Vault folders resolve

You can run a workspace command from the repo root or any nested local folder. Authsia searches upward for the nearest .authsia/workspace.json, uses that workspace's saved environment, and keeps the child command in your current directory. It loads only managed env files at the workspace root or in ancestor directories of that current directory. A nearer nested workspace config defines a separate workspace and selection.

Explicit one-run env-file definitions outrank configured workspace definitions. A one-run --environment or --default-only selects the environment for that run.
With a named environment active, matching tagged items outrank untagged Default-environment items.
Within the same environment tier, the nearest applicable managed env-file directory wins.
Among remaining items, the most deeply nested Vault folder wins.
Equal definitions at the same applicable scope and other unresolved ties produce a conflict; Authsia does not run the command. Sibling env-file directories are independent command scopes.

For example, with Production active, a root Production item wins over a nested Default item. If both env-file definitions are tagged Production, the nested applicable definition wins. Guarded-terminal shims apply the same rules on every command, so changing the active environment affects the next guarded command without reopening the terminal.

1. Preview setup

Review env files and detected values before anything is written.

2. Apply selected refs

Store selected secrets under a workspace folder and write refs locally.

3. Run from the boundary

Authsia resolves refs in the child process, not the parent shell.

Preview without an approval interruption

workspace status, workspace env validate, workspace run preflight, workspace sync --dry-run, workspace sync --plan-json, and config-safe workspace sync --apply-json use a no-approval, metadata-only request limited to CLI-enabled items in the configured workspace folder. Env validation sends only the exact configured references and performs targeted password/API-key existence checks; run adds exact references from applicable managed or one-run env files before secret-bearing execution continues through exec. If scoped metadata is unavailable, validation reports unverified and run fails closed. Sync treats valid Authsia references in managed env files as tracked alongside explicit workspace env bindings, so matching vault items are not reported as local extras. Apply uses the same scoped metadata only to validate the selected plan before writing workspace references. These paths work for local coding agents and while the app is locked. Item names, types, folder paths, and existence can be visible; secret values never are. Direct list, secret access, imports, copies, moves, creates, and vault writes keep their approval, session, automation, or JIT controls.

Guarded terminal

Guarded mode prepends Authsia shims for common developer tools. Interactive humans keep convenient secret resolution; agent harness invocations do not get workspace secrets implicitly. When a named environment is active, the first terminal message names it and confirms that Default-environment items remain available.

Default tool families

npm, pnpm, yarn, python, pip, docker, aws, gcloud, az, kubectl, helm, terraform, tofu, terragrunt, pulumi, and ansible-playbook.

Run authsia setup --repair once and open a new terminal first. Without shell integration the command exits non-zero with repair guidance. The low-level workspace guard --print-env form remains available for scripts and extra shim options.

Restarts the current shell in the same folder and skips Auto-guard once. Workspace variables cleared by guard remain cleared. Without shell integration the command exits non-zero with repair guidance.

Agent JIT approvals

Agents should ask through Authsia boundaries, not scrape plaintext secrets. Access Center makes the grant visible and revocable.

A named-folder grant covers that folder and slash-delimited descendants, never ancestors or siblings. Root is root-only. Covered descendants reuse an ancestor grant; unrelated trees or a new capability can require a clearly explained approval. A first broad unscoped list with no active grants says “across all resolved folders”; only a follow-up with active grants lists new paths and active scopes. Broad prompts never show item or secret names. JIT permits only scoped list and exec, with caller, TTL, revocation, audit, and CLI-enabled checks still enforced.

Without an explicit automation credential, confirmed agent context uses JIT; automation credentials follow their separate authorization path. IDE ancestry alone becomes an ongoing human session only with stdin attached to a TTY and a server-current token for the same terminal scope. TTY alone and active JIT grants are not human authorization. First use may ask for biometrics, returns nothing before approval, and then creates the normal terminal session; redirecting stdout does not change this routing. CLI and SSH approval sessions are configurable up to 24 hours; legacy Never preferences are treated as 24 hours.

JIT grants are created by approval-bound preflight. authsia access create instead creates reusable, machine-bound automation authorization with its own TTL, scope, and capabilities; it is not a JIT grant.

authsia agent init --agent claude-code safely merges exact Authsia hooks and the SSH-agent socket value into compatible Claude settings while removing legacy Authsia Mach lookup values. Repeats are idempotent; reset removes exact Authsia entries while preserving custom content, and leaves unsafe shapes unchanged with manual guidance.

Agent file activity is local display evidence only. Authsia stores path metadata from supported hooks, including action, status, source, and confidence; it does not store file contents, command output, stdin, environment values, or plaintext secrets. JSON export uses workspace-relative paths for workspace-contained file activity.

Direct: A supported hook reported the file or directory for the tool call.
Confirmed: A post-tool hook reported success for the same tool call.
Inferred: Authsia detected a workspace change during the session, not a direct read.
Fallback: Activity was associated by terminal or session scope and working directory.

File activity does not grant or deny access. Secret access still depends on JIT grants, bridge policy, folder-tree or root-only scope, capability, TTL, and audit records.

authsia workspace agent marks the launched Codex, Claude Code, VS Code Copilot, Cursor, or Windsurf process with its agent platform and AUTHSIA_AGENT_INVOKES_AUTHSIA=1. The markers select agent JIT routing but grant no access by themselves; normally opened IDEs and terminals remain direct human CLI.

SSH signing

Adopt keys into Authsia, then let Git and SSH use the local Authsia agent through shell integration.

Audit and recovery

Use audit commands to review workspace, agent, and selected-environment attribution without secret values, and workspace status/update/reset when refs drift from the vault.

Compact command map

Enough reference to get oriented, without turning the page into a manual.

Command	Use it for	Example
status	App, bridge, shell, and SSH agent state	authsia status --format json
workspace	Repo setup, refs, guarded runs, sync, reset	authsia workspace run -- npm test
guard	Activate guarded mode in the current shell	authsia guard
unguard	Restart the current tab in normal terminal mode	authsia unguard
exec	Resolve selected vault items into one child process	authsia exec api-key Stripe --field key -- npm start
list	Metadata-only vault listing	authsia list api-keys --format table
read	Resolve one authsia:// secret reference	authsia read "authsia://api-key/Stripe/key"
add api-key	Store API keys without a username field	authsia add api-key --name Stripe --key -
convert	Move password-style tokens into API Keys	authsia convert password Stripe --to api-key
ssh	Adopt, generate, sign, and configure SSH keys	authsia ssh adopt --path ~/.ssh --dry-run
access	Manage automation access credentials	authsia access list --format table
audit	Local access history	authsia audit list

For the complete command surface, run authsia --help locally. The shipped CLI help stays the source of truth for every option.