Compact command map
Orientation only. Local authsia --help remains the option source of truth.
| Command | Use it for | Example |
|---|---|---|
| status | App, bridge, Direct CLI session or IDE pairing, shell, guarded-terminal, and SSH agent state | authsia status --format json |
| workspace | Repo setup, refs, guarded runs, sync, reset | authsia workspace run -- npm test |
| agent init | Install setting-aware agent rules plus supported command-attribution and sub-agent-lineage hooks | authsia agent init --agent codex |
| mcp configure | Print-only recipe plus a table of that client's current launches | authsia mcp configure --client codex |
| mcp start | Start the app-owned MCP Manager and open its authenticated portal | authsia mcp start |
| mcp status | Report manager, registry, portal, and localhost HTTP readiness | authsia mcp status --json |
| mcp stop | Stop manager listeners without stopping existing STDIO proxies | authsia mcp stop |
| mcp restart | Restart manager listeners and invalidate portal sessions | authsia mcp restart |
| mcp wrap | Declare and protect one scanned local MCP launch after review; plan redacts env values | authsia mcp wrap --write --server jira |
| mcp declare | Declare a STDIO child command or validated localhost HTTP endpoint | authsia mcp declare --server internal --url http://127.0.0.1:9000/mcp --allow search --yes |
| mcp unwrap | Preview and restore a protected launch while retaining workspace policy | authsia mcp unwrap --write --server jira |
| mcp catalog | Record what a declared local MCP server advertises, so clients list its tools without starting it | authsia mcp catalog --server codegraph --write |
| mcp serve | Bind a validated workspaceRoot tool input or safe launch context | authsia mcp serve --workspace /path/to/repo |
| mcp proxy | Admit one workspace-declared stdio MCP; secret refs use Agent JIT | authsia mcp proxy --upstream jira |
| mcp doctor | Default table of scanned launches plus a verdict; exit 2 on effective or conditional bypass. JSON v2 includes host, version, MCP Integrations, and audit integrity | authsia mcp doctor --json |
| mcp activity export | Copy redacted MCP proxy command-history rows | authsia mcp activity export --json --unowned |
| guard | Activate guarded mode in the current shell | authsia guard |
| unguard | Restart the current tab in normal terminal mode | authsia unguard |
| exec | Resolve selected items or, with shell integration, shell-local authsia:// refs into one child process | API_KEY=authsia://… authsia exec -- npm start |
| list | Metadata-only vault listing; scraped items default to this machine | authsia list api-keys --format table |
| completion | Shell scripts and metadata suggestions; automation uses list permission | eval "$(authsia completion zsh)" |
| 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 - |
| edit | Update fields, move to a folder, or move any editable vault item to Root with --clear-folder | authsia edit password GitHub --clear-folder |
| 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 |
Shell profile imports resolve on demand
Vault import and authsia scrape replace secret assignments in shell profiles with quoted exports such as export API_KEY='authsia://api-key/API_KEY/key'. Opening an IDE or sourcing the profile only exports the reference; these assignments never fetch secrets or request pairing at startup.
Run authsia exec -- npm start when a command needs the secrets. Authsia resolves the exported references into that command's environment after the required approval or pairing. The parent shell keeps the URIs, and no shell integration is needed for these exported references. Commands launched directly receive the URI strings.
Older imports may have written authsia load ... --silent into a profile. Replace those lines with the corresponding URI exports to defer resolution. Updating Authsia does not automatically rewrite existing profiles.
Credential files resolve on demand
For tools that expect a file path, add ?as=file to a reference. Vault import and authsia scrape store complete credential documents as Password items and use this option when replacing credential-path assignments in shell or env files. Existing Notes can also supply file content.
export GOOGLE_APPLICATION_CREDENTIALS='authsia://password/gcp-service-account/password?as=file'
authsia exec -- python3 app.py
export KUBECONFIG='authsia://note/kubeconfig/content?as=file'
authsia exec -- kubectl get podsAfter the required approval, the child receives a private temporary file path. Files have 0600 permissions inside a 0700 directory and are removed when the foreground command exits, including failure or a forwarded signal. If the wrapper is killed without cleanup, the next file-based execution removes abandoned files once both the wrapper and recorded child have exited. Keep background tasks inside the foreground command's lifetime.
The first version supports self-contained kubeconfigs, including a single extensionless ~/.kube/config. External certificate, key, token, and relative authentication-helper paths must be resolved before file delivery; import keeps those source assignments unchanged and explains the issue. Multi-file kubeconfig lists are not rewritten. Original credential documents remain intact.
The same references work in env files and Workspace bindings through authsia workspace run. Combine folder scoping with ?folder=Cloud&as=file. Sourcing the profile only exports the URI. Ordinary references still deliver values, and read and inject still return or insert raw content. MCP environment resolution currently rejects file delivery with guidance to use exec or Workspace. No existing vault items or profiles are automatically converted.