> ## Documentation Index > Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 ` | Authenticate with PROVIDER using the configured flow. | | `logout ` | Log out of the specified PROVIDER connection. | | `provider` | Manage provider definitions and provider-level operations. | | `run -- ` | 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 for the rotating client debug log file. Pass `""` to disable. Default: `~/.authsome/client/logs/authsome.log`. | ## Command details ### `onboard` / `whoami` / `doctor` ```bash theme={null} 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 `. 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 ` | 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` ```bash theme={null} 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` ```bash theme={null} authsome login [OPTIONS] ``` | Option | Description | | --------------------- | ----------------------------------------------------------------------------------- | | `--flow ` | Override the auth flow. Valid values: `pkce`, `device_code`, `dcr_pkce`, `api_key`. | | `--connection ` | Connection name. Default: `default`. | | `--scopes ` | Comma-separated scopes to request. | | `--base-url ` | Override the base URL for multi-tenant providers. | | `--force` | Overwrite an existing connection without prompting. | Examples: ```bash theme={null} 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` ```bash theme={null} authsome run -- [args...] ``` Runs `` behind a local HTTP proxy that injects auth headers into matched outbound requests. The child process never sees the raw secret. ```bash theme={null} 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](/concepts/proxy-injection) for the routing contract. ### `connections set-default` ```bash theme={null} authsome connections set-default ``` Sets the default connection for a provider. The proxy and library calls use the default unless an explicit `--connection` flag is passed. ```bash theme={null} authsome connections set-default github work ``` ### `agent` ```bash theme={null} 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` ```bash theme={null} 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 | ```bash theme={null} authsome logout github --connection work authsome provider revoke github authsome provider remove acmecrm ``` ### `provider register` ```bash theme={null} authsome provider register [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`. ```bash theme={null} 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](/guides/custom-providers) for full templates. ### `log` ```bash theme={null} 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.