CLI reference

Every authsome command, flag, and exit code.

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.

Examples:

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...]

Runs <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

How it works:

1. Starts a local proxy on an ephemeral port.
2. Launches the child with HTTP_PROXY / HTTPS_PROXY set.
3. Sets placeholder env vars (e.g. OPENAI_API_KEY=authsome-proxy-managed) so SDKs initialize.
4. Intercepts matched requests and injects the real auth headers.
5. Stops the proxy on child exit.
6. Returns the child’s exit code.

See Proxy injection for the routing contract.

connections set-default

authsome connections set-default <provider> <connection>

Sets the default connection for a provider. The proxy and library calls use the default unless an explicit --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

Agents are backed by Ed25519 signing keys at ~/.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).

Validates the JSON, copies it into ~/.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

See Custom providers for full templates.

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

Reads from ~/.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

Note: Click argument validation errors (missing required argument, unknown option) also produce exit code 2 via Click’s own mechanism.

When --json is passed and a command fails, the structured output includes "error" and "message" keys.