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
whoami	Show local identity context and encryption mode.
doctor	Run health checks on identity, providers, vault, and store integrity.
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, shell, 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.
set-default <provider> <connection>	Set the default connection for a provider.
profile	Manage local profiles backed by identity keys.
ui	Open the dashboard in the browser.
log	View structured audit entries.
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 (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

whoami / doctor

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

list / inspect

authsome list                      # all providers + connection states
authsome list --json               # machine-readable, bundled + custom arrays
authsome inspect github            # full provider definition + connections as JSON

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

get

authsome get <provider> [OPTIONS]

Option	Description
--connection <name>	Connection name. Default: default.
--field <field>	Return only the value of a specific field.
--show-secret	Reveal encrypted secret values in output.

authsome get github                                  # metadata, secrets redacted
authsome get github --field status                   # → connected
authsome get github --field access_token --show-secret

export

authsome export <provider> [OPTIONS]

Option	Description
--connection <name>	Connection name. Default: default.
--format <fmt>	Output format: env (default), shell, or json.

authsome export github --format env      # KEY=value lines
authsome export github --format shell    # export KEY=value (sourceable)
authsome export openai --format json     # JSON object

Only the access_token (OAuth2) or api_key (API-key) is exported. Refresh tokens are never exposed — authsome handles refresh transparently.

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.

scan

authsome scan [OPTIONS]

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.

set-default

authsome 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 set-default github work

profile

authsome profile create   # create a new local profile keypair
authsome profile use      # switch the active local profile

Profiles are backed by Ed25519 identity keys at ~/.authsome/identities/. Each profile has its own credential namespace in the vault. See Profiles vs Connections for the distinction.

ui

authsome ui [--no-browser]

Opens the daemon dashboard in your default browser at 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).

authsome daemon serve [--host 127.0.0.1] [--port 7998] [--reload]
authsome daemon start
authsome daemon stop
authsome daemon restart
authsome daemon status
authsome daemon logs [-n 100]

• serve runs the daemon in the foreground (blocks the terminal).
• start / stop / restart manage a background daemon.
• status prints health, PID file path, and log file path as JSON.
• 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 default (bundled)	Not contacted

authsome logout github --connection work
authsome revoke github
authsome remove acmecrm

register

authsome 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 list.

authsome register ./acme.json             # prompt before registering
authsome register ./acme.json --force     # overwrite existing, no prompt
authsome 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, export, and get --show-secret, 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.