Documentation Index
Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
All commands support --json for machine-readable output, --quiet to suppress non-essential output, and --no-color to disable ANSI colors.
Commands at a glance
| Command | Description |
|---|
whoami | Show home directory and encryption mode. |
doctor | Run health checks on directory layout and encryption. |
list | List all providers (bundled and custom) and their connection states. |
inspect <provider> | Show the full provider definition and any connections. |
login <provider> | Authenticate with a provider using its configured flow. |
get <provider> | Get connection metadata (secrets redacted by default). |
export <provider> | Export credentials in env or json format. |
run -- <cmd> | Run a subprocess behind the local auth proxy. |
scan | Discover provider API keys in env files and the current environment. |
logout <provider> | Log out of a connection and remove local state. |
revoke <provider> | Reset all connections and client secrets for the provider. |
remove <provider> | Uninstall a custom provider or reset a bundled one. |
register <path> | Register a custom provider from a JSON file. |
connection set-default <provider> <connection> | Set the default connection for a provider. |
ui | Open the dashboard in the browser. |
log | View the audit log. |
daemon <subcommand> | Manage the local daemon: serve, start, stop, restart, status, logs. |
Global flags
| Flag | Description |
|---|
--json | Output in machine-readable JSON. |
--quiet | Suppress non-essential output. |
--no-color | Disable ANSI colors. |
-v, --version | Print the authsome version. |
--verbose | Enable DEBUG logging to stderr. |
--log-file <path> | Path for the rotating log file. Pass "" to disable. Default: ~/.authsome/logs/authsome.log. |
Command details
whoami / doctor
uvx authsome whoami # show home directory and encryption mode
uvx authsome doctor # run health checks
doctor exits with 0 if all checks pass and a non-zero code otherwise. Use --json for structured output suitable for monitoring.
list / inspect
uvx authsome list # all providers + connection states
uvx authsome inspect github # full provider definition
uvx authsome inspect github --json # same, as JSON
list shows three states per provider. available, configured, connected. See Credential storage for the state model.
login
uvx authsome login <provider> [OPTIONS]
| Option | Description |
|---|
--flow <type> | Override the auth flow. Valid values: pkce, device_code, dcr_pkce, api_key. |
--connection <name> | Connection name. Default: default. |
--scopes <s1,s2> | Comma-separated scopes to request. |
--base-url <url> | Override the base URL for multi-tenant providers. |
--force | Overwrite an existing connection. |
uvx authsome login github # OAuth2 PKCE flow
uvx authsome login github --flow device_code # headless OAuth2
uvx authsome login openai # API-key flow via browser bridge
uvx authsome login github --connection work # second connection on the same provider
uvx authsome login github --base-url https://github.acme.com # GitHub Enterprise
Sensitive values. client_secret, API keys, are never accepted as command-line arguments. Authsome collects them through the secure browser bridge or, on headless machines, through masked terminal input.
get
uvx authsome get <provider> [OPTIONS]
| Option | Description |
|---|
--connection <name> | Connection name. Default: default. |
--field <field> | Return only a specific field. |
--show-secret | Reveal encrypted secret values in output. |
uvx authsome get github # metadata, secrets redacted
uvx authsome get github --field status # → connected
uvx authsome get github --field access_token --show-secret
export
uvx authsome export <provider> [OPTIONS]
| Option | Description |
|---|
--connection <name> | Connection name. Default: default. |
--format <fmt> | Output format: env (default) or json. |
uvx authsome export github --format env # KEY=value lines
uvx authsome export openai --format json # JSON object
access_token (OAuth2) or api_key (API-key) is exported. Refresh tokens are never exposed, authsome handles refresh transparently.
run
uvx authsome run -- <command> [args...]
<command> behind a local HTTP proxy that injects auth headers into matched outbound requests. The child process never sees the raw secret.
uvx authsome run -- python my_agent.py
uvx authsome run -- curl https://api.openai.com/v1/models
- Starts a local proxy on an ephemeral port.
- Launches the child with
HTTP_PROXY / HTTPS_PROXY set.
- Sets placeholder env vars (e.g.
OPENAI_API_KEY=authsome-proxy-managed) so SDKs initialize.
- Intercepts matched requests and injects the real auth headers.
- Stops the proxy on child exit.
- Returns the child’s exit code.
See Proxy injection for the routing contract.
scan
uvx authsome scan [OPTIONS]
.env files in the current directory tree and the active process environment for credentials matching bundled providers. By default it prints a drift report (what’s in your env vs. what’s in the vault).
| Option | Description |
|---|
--import | Apply the discovered values, creating connections in the vault. |
--connection <name> | Target a non-default connection name when importing. |
--json | Machine-readable drift report. Combine with --import to apply. |
uvx authsome scan # report-only
uvx authsome scan --json # report-only, JSON output
uvx authsome scan --import # write discovered keys into the vault
uvx authsome scan --import --connection ci # import into a named connection
scan does not support --quiet. Use --json for headless contexts.
connection set-default
uvx authsome connection set-default <provider> <connection>
--connection flag is passed.
uvx authsome connection set-default github work
uvx authsome ui [--no-browser]
http://127.0.0.1:7998/ui/. Pass --no-browser to just print the URL.
daemon
Daemon lifecycle management. The CLI normally auto-starts the daemon on first use; these subcommands let you control it explicitly (useful for systemd units, debugging, and CI).
uvx authsome daemon serve [--host 127.0.0.1] [--port 7998] [--reload]
uvx authsome daemon start
uvx authsome daemon stop
uvx authsome daemon restart
uvx authsome daemon status
uvx authsome daemon logs [-n 100]
serve runs the daemon in the foreground (blocks the terminal).start / stop / restart manage a background daemon.status prints PID, base URL, and uptime.logs tails the daemon log file.
logout / revoke / remove
| Command | Local state | Remote provider |
|---|
logout | Removes the connection record | Not contacted |
revoke | Removes all connections + client credentials | Calls revocation endpoint where supported |
remove | Removes the provider entirely (custom) or resets to bundled (bundled) | Not contacted |
uvx authsome logout github --connection work
uvx authsome revoke github
uvx authsome remove acmecrm
register
uvx authsome register <path/to/provider.json> [--yes] [--force]
~/.authsome/providers/, and confirms the new provider appears in authsome list. Use --yes to skip the confirmation prompt in scripts, and --force to overwrite an existing provider with the same name.
See Custom providers for full templates.
log
uvx authsome log # last 50 audit entries
uvx authsome log -n 200 # last 200
uvx authsome log --json # one JSON object per line, parsed
~/.authsome/audit.log. Each entry records actions like login, logout, revoke, export, and get --show-secret.
Exit codes
| Code | Meaning |
|---|
0 | Success |
1 | Generic failure |
2 | Invalid usage |
3 | Provider not found |
4 | Authentication failed |
5 | Credential missing |
6 | Refresh failed |
7 | Store unavailable |
8 | User cancelled credential entry |
--json is passed and a command fails, the structured output includes an error and message key on stderr-friendly format.