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 |
|---|
connections | Inspect and manage stored provider connections. |
daemon | Manage the local Authsome daemon. |
doctor | Run health checks on directory layout and encryption. |
init | Initialize local storage and register a fresh profile. |
log | View structured audit entries or the raw client debug log. |
login <provider> | Authenticate with PROVIDER using the configured flow. |
logout <provider> | Log out of the specified PROVIDER connection. |
profile | Manage local profiles backed by identity keys. |
provider | Manage provider definitions and provider-level operations. |
run -- <cmd> | Run COMMAND as a subprocess injected with authentication credentials. |
scan | Scan env files and process env for provider API keys. |
whoami | Show basic local context. |
Global flags
| Flag | Description |
|---|
--json | Output in machine-readable JSON. |
--quiet | Suppress non-essential output (banners, status messages). Primary data rows always print. |
--no-color | Disable ANSI colors. |
-v, --version | Print the authsome version. |
--verbose | Enable DEBUG logging to stderr. |
--log-file <path> | Path for the rotating client debug log file. Pass "" to disable. Default: ~/.authsome/client/logs/authsome.log. |
Command details
init / whoami / doctor
authsome init # initialize local storage and register profile
authsome whoami # show identity context and encryption mode
authsome doctor # run health checks
authsome doctor --json # structured output for monitoring
doctor runs six checks and exits 0 when all pass:
| Check | What it verifies |
|---|
spec_version | Server spec version is compatible |
identity | Active identity key is present and readable |
providers | Provider registry loads without error |
connections | Connection store is accessible |
vault | Vault roundtrip (put / get / delete) succeeds |
integrity | Store integrity check passes |
provider list / provider inspect / connections inspect
authsome provider list # all providers + connection states
authsome provider list --json # machine-readable, bundled + custom arrays
authsome provider inspect github # full provider definition + connections as JSON
authsome connections inspect github # full connection details + credentials (redacted)
--quiet suppresses the summary header (Providers: N total, N connected) but always prints the table.
login
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 without prompting. |
authsome login github # OAuth2 PKCE flow
authsome login github --flow device_code # headless OAuth2
authsome login openai # API-key flow via browser bridge
authsome login github --connection work # second connection on the same provider
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.
run
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.
authsome run -- python my_agent.py
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
Scans .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. |
authsome scan # report-only
authsome scan --json # report-only, JSON output
authsome scan --import # write discovered keys into the vault
authsome scan --import --connection ci # import into a named connection
scan does not support --quiet. Use --json for headless contexts.
connections set-default
authsome connections set-default <provider> <connection>
--connection flag is passed.
authsome connections set-default github work
profile
authsome profile create # create a new local profile keypair
authsome profile use # switch the active local profile
~/.authsome/identities/. Each profile has its own credential namespace in the vault.
daemon
authsome daemon serve # run the daemon in the foreground
authsome daemon start # start the local daemon in the background
authsome daemon stop # stop the local daemon
authsome daemon restart # restart the local daemon
authsome daemon status # show daemon status
authsome daemon logs # show daemon log output
logout / provider revoke / provider remove
| Command | Local state | Remote provider |
|---|
logout | Removes the connection record | Not contacted |
provider revoke | Removes all connections + client credentials | Calls revocation endpoint where supported |
provider remove | Removes the provider entirely (custom) or resets to bundled default (bundled) | Not contacted |
authsome logout github --connection work
authsome provider revoke github
authsome provider remove acmecrm
provider register
authsome provider register <path/to/provider.json> [OPTIONS]
| Option | Description |
|---|
--force | Overwrite an existing provider with the same name without prompting. |
--yes | Skip the confirmation prompt (without forcing an overwrite). |
~/.authsome/providers/, and confirms the new provider appears in authsome provider list.
authsome provider register ./acme.json # prompt before registering
authsome provider register ./acme.json --force # overwrite existing, no prompt
authsome provider register ./acme.json --yes # skip prompt, fail if already exists
log
authsome log # last 50 structured audit entries
authsome log -n 200 # last 200 entries
authsome log --json # entries as a parsed JSON array
authsome log --raw # raw client debug log (loguru format)
authsome log --raw -n 20 # last 20 lines of the client debug log
~/.authsome/server/logs/authsome.log (the server-side structured audit log). Each entry records actions like login, logout, revoke, and scan, with fields: timestamp, event, provider, connection, identity, status.
The --raw flag switches to the client-side debug log at ~/.authsome/client/logs/authsome.log (loguru format, DEBUG level).
Exit codes
| Code | Meaning | Error class |
|---|
0 | Success | — |
1 | Unexpected failure | Unclassified exceptions |
2 | Authentication failed or input cancelled | AuthenticationFailedError, InputCancelledError |
3 | Connection not found | ConnectionNotFoundError |
4 | Provider not found or operation not allowed | ProviderNotFoundError, OperationNotAllowedError |
5 | Credential missing or token expired | CredentialMissingError, TokenExpiredError, RefreshFailedError |
6 | Connection already exists | ConnectionAlreadyExistsError |
7 | Provider already registered | ProviderAlreadyRegisteredError |
8 | Endpoint unreachable | EndpointUnreachableError |
9 | Daemon unavailable | DaemonUnavailableError |
2 via Click’s own mechanism.
When --json is passed and a command fails, the structured output includes "error" and "message" keys. 
