Authsia CLI

Bring Authsia to your terminal. Install, wire a workspace, connect an MCP client, guard a terminal, approve agents, then audit. Commands stay short; each guide carries the rules.

Use cases

Keep plaintext out of repos

Initialize commit-safe authsia:// refs and resolve them in the child process.

Workspace CLI

Connect local coding agents

Six fixed MCP tools and no secret-return path. The client launches Authsia.

MCP

Manage and protect local MCP

Use the local portal for existing STDIO protection and authenticated localhost Streamable HTTP.

MCP Manager

Approve scoped agent access

Folder, capability, and TTL — then revoke from Access Center or a paired iPhone.

Agent JIT

Quickstart

If you are installing Authsia for the first time, start here.

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

# prepare the repo
authsia workspace init
authsia workspace status
authsia agent init --agent codex

# run commands through Authsia
authsia workspace run -- npm test
authsia mcp configure --client codex
authsia guard

Guides

Workspace and terminal

authsia workspace env remove can remove stale bindings even when unrelated MCP configuration needs repair. Vault items and MCP settings stay unchanged.

Agents and MCP

Before authsia mcp start or restart, unlock the Authsia app. A locked app reports the unlock-and-retry step; this is separate from tool-call JIT approval.

Workspace setup also merges Copilot hooks into existing compatible settings automatically, preserving custom settings and adding only missing Authsia hooks.

Platform-only CLI environment markers preserve matching hook sub-agent identity. Claude Code and Codex MCP hooks capture only caller metadata for list, execution, and revocation; MCP server and invocation IDs remain separate. Missing or competing candidates display as sub-agent unknown. Attribution is display-only and never changes authorization. After upgrading, rerun authsia agent init --agent claude in existing Claude projects, or authsia agent init --agent codex in Codex projects. Restart the coding client and its MCP connection after refreshing hooks. Codex setup adds and trusts the MCP hook automatically.

Cursor and Codex wraps store launcher arguments separately and share case-insensitive upstream policy names. Connected stdio proxies notify clients when catalog or policy changes affect their tool list.

Cursor STDIO protection binds the selected project's configuration to its absolute workspace using WORKSPACE_FOLDER_PATHS, avoiding unresolved launch hints. The global fallback stays unpinned. After Protect, Finish setup in Cursor explains enable and reload steps for the Workspace source (STDIO) or User source (HTTP); Authsia cannot perform or verify those steps. Disabled direct entries must be protected before enabling. Devin and VS Code global entries use their launch context without a saved project pin.

Claude Code, including its VS Code extension, passes its project directory to the proxy at runtime. Codex CLI and its VS Code extension use their own session launch context. Neither needs a generated global project pin; conflicting proxy workspace hints fail closed.

MCP Manager shows protection per client in Servers. Managed wraps retain a safe launch definition for reviewed recovery in another workspace; older Context7 entries offer the official preset without requiring manual command entry.

Catalog capture defaults all recorded tools to allow when policy is empty. Existing policy choices are preserved. Review permissions in MCP Manager > Edit policy. Verified audit export includes management changes; Activity reports its bounded retention separately.

MCP setup and launch commands require MCP Integrations in Authsia Settings > Developer Access. If it is off, enable it in the app and retry. Status, diagnostics, and stop remain available.

Codex IDE chat initialization accepts unsupported experimental capability objects without changing tool policy. HTTP startup GET probes do not request JIT; admission starts with the first permitted tool call. Removing Codex HTTP routing also removes its nested header tables.

SSH and audit

Reference