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. |
agent | Manage local agents backed by signing keys. |
onboard | First-run setup: identity, claim, and API key import from env. |
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. |
provider | Manage provider definitions and provider-level operations. |
run -- <cmd> | Run COMMAND as a subprocess injected with authentication credentials. |
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
onboard / whoami / doctor
authsome onboard # identity + claim + import API keys from env
authsome onboard --base-url https://host:7998 # point at a remote daemon (saved for later runs)
authsome onboard --scan-only # drift report without importing
authsome whoami # show agent context and encryption mode
authsome doctor # run health checks
authsome doctor --json # structured output for monitoring
onboard is idempotent — safe to re-run. It creates a local identity when needed, completes daemon registration and claim, then imports API keys discovered in .env files and the process environment. OAuth providers still require authsome login <provider>.
When --base-url is passed, the URL is persisted in ~/.authsome/client/config.json as daemon_base_url and used automatically on subsequent commands (unless overridden by AUTHSOME_BASE_URL).
| Option | Description |
|---|
--base-url <url> | Daemon URL to connect to; saved in client config for future commands. |
--scan-only | Report env/vault drift without importing discovered keys. |
onboard does not support --quiet. Use --json for headless contexts.
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.
connections set-default
authsome connections set-default <provider> <connection>
--connection flag is passed.
authsome connections set-default github work
agent
authsome agent create # create a new local agent keypair
authsome agent use # switch the active local agent
~/.authsome/identities/. Credentials are scoped to the active vault, not to the agent key.
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 onboard, 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. 
