agentrhq__authsome/docs/site/reference/cli.mdx

---
title: "CLI reference"
description: "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`

```bash
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`

```bash
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
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:

```bash
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
```

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

### `run`

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

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

```bash
authsome connections set-default github work
```

### `agent`

```bash
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
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
authsome logout github --connection work
authsome provider revoke github
authsome provider remove acmecrm
```

### `provider register`

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

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