authsome 0.3.0__tar.gz → 0.3.1__tar.gz

authsome-0.3.1/.github/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.1"
+}

{authsome-0.3.0 → authsome-0.3.1}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.3.1](https://github.com/agentrhq/authsome/compare/authsome-v0.3.0...authsome-v0.3.1) (2026-05-17)
+
+
+### Bug Fixes
+
+* **cli:** resolve three CLI bugs and improve audit log command ([3b990e3](https://github.com/agentrhq/authsome/commit/3b990e3cae998d9ccaccb421b5cb577c2bb89de3))
+* **cli:** resolve three CLI bugs, improve audit log, and sync docs ([dd9cad3](https://github.com/agentrhq/authsome/commit/dd9cad326cb2817826eb8e5b8bb42f5f3df8e2a2))
+
+
+### Documentation
+
+* **cli:** sync reference and manual-testing guide with 0.3.0 implementation ([bdf659f](https://github.com/agentrhq/authsome/commit/bdf659ffffc0a0c2100cc21508daec042161656e))
+
 ## [0.3.0](https://github.com/agentrhq/authsome/compare/authsome-v0.2.4...authsome-v0.3.0) (2026-05-15)
 
 

{authsome-0.3.0 → authsome-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authsome
-Version: 0.3.0
+Version: 0.3.1
 Summary: A portable local authentication library for AI agents and developer tools
 Author-email: Manoj Bajaj <manojbajaj95@gmail.com>
 License-Expression: MIT

authsome-0.3.1/docs/internal/cli-design-review.md

@@ -0,0 +1,253 @@
+# CLI Design Review — authsome 0.3.0
+
+_Generated: 2026-05-17_
+_Scope: audit of the CLI surface against (1) published docs, (2) implementation, (3) industry conventions (clig.dev, gh, stripe, fly, kubectl)._
+
+---
+
+## Summary
+
+Three categories of issues:
+
+1. **Docs vs. implementation gaps** — documented behavior that the code no longer matches.
+2. **Implementation bugs** — the code is broken relative to stated intent.
+3. **Design gaps vs. industry conventions** — opportunities to align with well-established patterns.
+
+---
+
+## 1. Docs vs. Implementation Gaps
+
+### 1a. Exit code table is completely wrong
+
+**`docs/site/reference/cli.mdx` says:**
+
+| Code | Meaning |
+|------|---------|
+| 2 | Invalid usage |
+| 3 | Provider not found |
+| 4 | Authentication failed |
+| 5 | Credential missing |
+| 6 | Refresh failed |
+| 7 | Store unavailable |
+| 8 | User cancelled credential entry |
+
+**`src/authsome/utils.py:format_error_code` actually does:**
+
+| Code | Exception(s) |
+|------|------|
+| 1 | Generic / unrecognized |
+| 2 | `AuthenticationFailedError`, `InputCancelledError` |
+| 3 | `ConnectionNotFoundError` |
+| 4 | `ProviderNotFoundError`, `OperationNotAllowedError` |
+| 5 | `CredentialMissingError`, `TokenExpiredError`, `RefreshFailedError` |
+| 6 | `ConnectionAlreadyExistsError` |
+| 7 | `ProviderAlreadyRegisteredError`, `FileExistsError` |
+| 8 | `EndpointUnreachableError` |
+| 9 | `DaemonUnavailableError` |
+
+Every code from 2 onwards maps to a different error than documented. Scripts checking exit codes against the published table will behave incorrectly. The table in the docs needs a full replacement.
+
+---
+
+### 1b. `set-default` is a top-level command, not `connection set-default`
+
+Docs say: `uvx authsome connection set-default <provider> <connection>`  
+CLI binary exposes: `authsome set-default <provider> <connection>` at the root
+
+The `connection` namespace documented does not exist. Running `authsome connection set-default` raises an error.
+
+---
+
+### 1c. `doctor` check names have changed
+
+Docs and manual-testing guide mention checks named `config`, `providers`, `vault`.  
+Current implementation returns: `spec_version`, `identity`, `providers`, `connections`, `vault`, `integrity`.  
+`config` is gone. Three new checks are present and undocumented.
+
+---
+
+### 1d. `--log-file` default path is wrong in docs
+
+Docs say default: `~/.authsome/logs/authsome.log`.  
+`--help` output shows: `~/.authsome/client/logs/authsome.log`.
+
+---
+
+### 1e. `profile` command exists but is not documented
+
+`authsome profile` with subcommands `create` and `use` appears in the CLI but is absent from `docs/site/reference/cli.mdx`.
+
+---
+
+### 1f. `export` has a `shell` format not documented
+
+`authsome export --format` accepts `env`, `json`, and `shell`.  
+The CLI reference documents only `env` and `json`.
+
+---
+
+### 1g. `daemon logs` subcommand — docs show `-n 100`, actual flag is different
+
+Docs say `authsome daemon logs [-n 100]`. Actual `authsome log` (client log command) uses `-n / --lines COUNT`.  
+These are two different commands (`daemon logs` tails the daemon log; `log` tails the client audit log) — the distinction and both flags need clear documentation.
+
+---
+
+## 2. Implementation Bugs
+
+### 2a. `doctor` renders `spec_version` as FAIL on every healthy system
+
+**Location:** `src/authsome/cli/main.py:930`, `src/authsome/server/routes/health.py:32`
+
+The server stores the spec version number as the value:
+```python
+checks["spec_version"] = str(current_spec_version())  # → "3"
+```
+
+The CLI checks `val == "ok"` for every key, so `"3" != "ok"` always renders `FAIL` even on a healthy install.
+
+**Fix (server side):** Return `"ok"` for a passing check; surface the version number in a separate key (e.g., `spec_version_number: "3"`).  
+**Fix (CLI side):** Treat `spec_version` as a special case that passes when the value is a numeric string.
+
+---
+
+### 2b. `--force` on `register` does not skip the confirmation prompt
+
+**Location:** `src/authsome/cli/main.py:698–733`
+
+The confirmation prompt checks only `yes` flag, not `force`. Running `authsome register --force` still prompts interactively; piping no input causes a generic failure (exit 1, no useful message).
+
+The `--force` flag is forwarded only to the server for the duplicate-override check. The client prompt is never bypassed.
+
+**Current state:** `--force` and `--yes` have different, non-overlapping effects. A full "force overwrite silently" requires `--force --yes`.  
+**Fix:** Either document the split explicitly in both `--help` and docs, or make `--force` imply `--yes` (the more ergonomic convention — `docker rm -f` and `git push --force` do not prompt).
+
+---
+
+### 2c. `--quiet` silences ALL output, including primary data
+
+**Location:** `src/authsome/cli/context.py:52–54`
+
+`echo()` returns immediately when `quiet=True`. This means `authsome --quiet list` produces zero output — the provider table is suppressed alongside any informational banners.
+
+**Industry convention (clig.dev, gh):** `--quiet` suppresses status messages, progress indicators, and banners. It does NOT suppress the primary result (data rows, IDs, URLs). Errors always print to stderr regardless of `--quiet`.
+
+**Fix:** Split `echo()` into a data path (`emit()`) and an info path (`note()`). Apply `quiet` suppression only to `note()`.
+
+---
+
+### 2d. `daemon stop` reports stopped but daemon immediately restarts
+
+`authsome daemon stop` outputs "Daemon stopped." and exits 0, but a subsequent `authsome daemon status` shows `running: true` within milliseconds. The guide test for `running: false` after stop cannot pass.
+
+Whether this is supervision auto-restart or a race in the status check is not confirmed, but the CLI output creates a misleading state. Either the daemon should indicate it will restart, or the stop command should wait for the process to actually stop before returning.
+
+---
+
+## 3. Design Gaps vs. Industry Conventions
+
+### 3a. `inspect` and `get` serve overlapping purposes
+
+Current situation:
+- `authsome get <provider>` — returns connection metadata; secrets redacted; accepts `--field`, `--show-secret`, `--json`
+- `authsome inspect <provider>` — returns full provider definition + connection summary as JSON (always)
+
+This creates confusion: users must know that `get` is for connection state and `inspect` is for provider config. The `--json` flag on `inspect` is redundant because `inspect` always outputs JSON.
+
+**Convention (kubectl, docker, gh):**
+- `describe` / `inspect` — human-readable detail combining metadata and context
+- `get` — scriptable, machine-readable fetch
+
+**Recommendation:** Make `inspect` human-readable (like `kubectl describe`) and `get` the JSON-native scriptable path. Or merge into a single `show <provider>` command that defaults to human-readable and accepts `--json`. Either way, the two commands should not both exist at the same conceptual level without a clear, documented distinction.
+
+---
+
+### 3b. `--force` and `--yes` semantics need to follow convention
+
+Industry standard (clig.dev, `gh`, `fly`):
+- `--yes` / `-y`: skip interactive confirmation prompts
+- `--force` / `-f`: override a safety constraint the tool would otherwise refuse
+
+Currently, `register --force` means "server-side overwrite" and `register --yes` means "skip client prompt" — this is a valid split, but it's not what most users expect when they reach for `--force`. The `--help` text for `--force` says "Force overwrite if provider exists" which implies the prompt is also skipped.
+
+**Recommendation:** `--force` should imply `--yes` (skips the prompt AND forces the overwrite). If the server-side distinction must be preserved, document it explicitly or rename the server-side flag to `--overwrite` internally.
+
+---
+
+### 3c. `set-default` should be under a command group
+
+`authsome set-default <provider> <connection>` at the top level is an outlier. It's a CRUD operation on a connection property, and the docs already (correctly) document it as `connection set-default`.
+
+**Convention (gh, kubectl, fly):** CRUD on a sub-resource belongs under a noun group. `kubectl label node`, `gh repo set-default`, `fly machine update` all group the resource type first.
+
+**Recommendation:** Implement `authsome connection set-default` as documented (or `authsome connection default <provider> <connection>` for a simpler form). Remove or alias the flat `set-default`.
+
+---
+
+### 3d. Exit code range is too wide
+
+The current scheme uses codes 1–9. `sysexits.h` reserves 64–78 for application errors; POSIX reserves 126–128+ for shell-level errors. Codes 1–9 are in the safe application range, but:
+
+- Code 2 is used for `AuthenticationFailedError` — but shells and Click both use 2 for "usage error / bad arguments". This clash means a usage error and an authentication failure are indistinguishable.
+- `gh` uses only 0, 1, 2, 4 and documents them clearly.
+
+**Recommendation:** Reserve 2 strictly for argument/usage errors (Click's default). Shift application errors to 3–9 (or adopt `sysexits.h` 64+ for a cleaner split). Update the docs table to match.
+
+---
+
+### 3e. `--json` is redundant on `inspect` and missing on `daemon status`
+
+- `inspect` always outputs JSON regardless of `--json` flag. The flag is a no-op but appears in `--help`, misleading users.
+- `daemon status` always outputs JSON. There is no human-readable plain-text mode for `daemon status`.
+
+**Recommendation:** 
+- `inspect` should have a human-readable default and use `--json` to switch to machine output (like every other command).
+- `daemon status` should follow the same pattern — plain text summary by default, `--json` for structured output.
+
+---
+
+### 3f. `remove` help text doesn't mention bundled providers
+
+`authsome remove --help` says "Permanently uninstall the specified custom PROVIDER definition."  
+The CLI reference says `remove` also "resets to bundled" when used on a bundled provider.
+
+If the behavior differs for bundled vs. custom providers, the `--help` text should say so. Users who accidentally run `authsome remove github` should know whether they're deleting something permanently or just resetting to defaults.
+
+---
+
+## Recommended Priority Order
+
+| Priority | Item | Effort |
+|----------|------|--------|
+| P0 | Fix `doctor` `spec_version: FAIL` rendering bug | Small |
+| P0 | Fix exit code documentation table | Small |
+| P1 | Fix `--quiet` — stop suppressing data output | Medium |
+| P1 | Fix `--force` on `register` — imply `--yes` or document split | Small |
+| P1 | Add `connection set-default` subgroup (or alias to match docs) | Small |
+| P1 | Document `profile` command, `shell` export format, corrected `--log-file` path | Small |
+| P2 | Resolve `inspect` vs `get` overlap — pick a clear model | Medium |
+| P2 | Add human-readable default to `inspect` and `daemon status` | Medium |
+| P2 | Fix `daemon stop` — wait for actual stop before returning | Medium |
+| P2 | Fix exit code 2 clash with Click usage errors | Small |
+| P3 | Update manual-testing.md to match current check names and exit codes | Small |
+
+---
+
+## Correct Exit Code Table (matches `format_error_code` as-is)
+
+Replace the table in `docs/site/reference/cli.mdx`:
+
+| 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) produce exit code 2 via Click's own mechanism — this overlaps with `AuthenticationFailedError`. Consider shifting application codes up by one (3 → authentication, 4 → connection not found, …) to cleanly reserve 2 for usage errors.

{authsome-0.3.0 → authsome-0.3.1}/docs/internal/manual-testing.md

@@ -32,13 +32,13 @@ uv run authsome whoami --json
 uv run authsome doctor
 ```
 
-**Expected:** Exit code `0`; `OK` printed for `config`, `providers`, `vault`.
+**Expected:** Exit code `0`; `OK` printed for `spec_version`, `identity`, `providers`, `connections`, `vault`, `integrity`.
 
 ```bash
 uv run authsome doctor --json
 ```
 
-**Expected:** `{"status": "ready", "checks": {"config": "ok", ...}}`.
+**Expected:** `{"status": "ready", "checks": {"spec_version": "ok", "identity": "ok", "providers": "ok", "connections": "ok", "vault": "ok", "integrity": "ok"}}`.
 
 ---
 
@@ -220,26 +220,32 @@ uv run authsome run --quiet curl -s https://api.resend.com/domains
 uv run authsome log
 ```
 
-**Expected:** Recent audit entries as newline-delimited JSON objects with `timestamp`, `event`, `provider`, `status`.
+**Expected:** Human-readable table of recent audit entries with columns `Timestamp`, `Event`, `Provider`, `Status`. Shows "No audit entries found." if empty.
 
 ```bash
 uv run authsome log -n 5
 ```
 
-**Expected:** Last 5 entries only.
+**Expected:** Last 5 entries only (same table format).
 
 ```bash
 uv run authsome log -n 5 --json
 ```
 
-**Expected:** Same entries as a JSON array.
+**Expected:** JSON object with `log_file` path and `entries` array of parsed audit event objects, each with `timestamp`, `event`, `provider`, `status`.
+
+```bash
+uv run authsome log --raw -n 10
+```
+
+**Expected:** Last 10 lines of the raw client debug log (loguru format).
 
 ---
 
 ## 11. Connection Management
 
 ```bash
-uv run authsome connection set-default github default
+uv run authsome set-default github default
 ```
 
 **Expected:** Confirmation that `default` is now the default connection for `github`.
@@ -279,11 +285,11 @@ uv run authsome list | grep test-custom
 **Expected:** Listed under `custom` source, `not_connected`.
 
 ```bash
-# Register again to test --force
+# Register again to test --force (overwrites without prompting)
 uv run authsome register /tmp/test-provider.json --force
 ```
 
-**Expected:** Overwrites existing without prompting for overwrite confirmation.
+**Expected:** Registers immediately, no confirmation prompt, no error.
 
 ```bash
 uv run authsome remove test-custom
@@ -372,19 +378,19 @@ uv run authsome --verbose get github
 uv run authsome login doesnotexist 2>&1; echo "exit: $?"
 ```
 
-**Expected:** `ProviderNotFoundError`, exit code `3`.
+**Expected:** `ProviderNotFoundError`, exit code `4`.
 
 ```bash
 uv run authsome inspect doesnotexist 2>&1; echo "exit: $?"
 ```
 
-**Expected:** `ProviderNotFoundError`, exit code `3`.
+**Expected:** `ProviderNotFoundError`, exit code `4`.
 
 ```bash
 uv run authsome logout doesnotexist 2>&1; echo "exit: $?"
 ```
 
-**Expected:** `ProviderNotFoundError`, exit code `3`.
+**Expected:** `ProviderNotFoundError`, exit code `4`.
 
 ```bash
 # Missing required argument
@@ -399,7 +405,7 @@ uv run authsome logout resend
 uv run authsome get resend 2>&1; echo "exit: $?"
 ```
 
-**Expected:** Non-zero exit; message indicates no connection found.
+**Expected:** `ConnectionNotFoundError`, exit code `3`.
 
 ---
 

{authsome-0.3.0 → authsome-0.3.1}/docs/site/reference/cli.mdx

@@ -9,22 +9,23 @@ All commands support `--json` for machine-readable output, `--quiet` to suppress
 
 | Command | Description |
 |---------|-------------|
-| `whoami` | Show home directory and encryption mode. |
-| `doctor` | Run health checks on directory layout and encryption. |
+| `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` or `json` format. |
+| `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. |
-| `connection set-default <provider> <connection>` | Set the default connection for a provider. |
+| `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 the audit log. |
+| `log` | View structured audit entries. |
 | `daemon <subcommand>` | Manage the local daemon: `serve`, `start`, `stop`, `restart`, `status`, `logs`. |
 
 ## Global flags
@@ -32,32 +33,42 @@ All commands support `--json` for machine-readable output, `--quiet` to suppress
 | Flag | Description |
 |------|-------------|
 | `--json` | Output in machine-readable JSON. |
-| `--quiet` | Suppress non-essential output. |
+| `--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 log file. Pass `""` to disable. Default: `~/.authsome/logs/authsome.log`. |
+| `--log-file <path>` | Path for the rotating client debug log file. Pass `""` to disable. Default: `~/.authsome/client/logs/authsome.log`. |
 
 ## Command details
 
 ### `whoami` / `doctor`
 
 ```bash
-uvx authsome whoami           # show home directory and encryption mode
+uvx authsome whoami           # show identity context and encryption mode
 uvx authsome doctor           # run health checks
+uvx authsome doctor --json    # structured output for monitoring
 ```
 
-`doctor` exits with `0` if all checks pass and a non-zero code otherwise. Use `--json` for structured output suitable 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`
 
 ```bash
 uvx authsome list                      # all providers + connection states
-uvx authsome inspect github            # full provider definition
-uvx authsome inspect github --json     # same, as JSON
+uvx authsome list --json               # machine-readable, bundled + custom arrays
+uvx authsome inspect github            # full provider definition + connections as JSON
 ```
 
-`list` shows three states per provider. `available`, `configured`, `connected`. See [Credential storage](/concepts/credential-storage#the-three-states) for the state model.
+`--quiet` suppresses the summary header (`Providers: N total, N connected`) but always prints the table.
 
 ### `login`
 
@@ -71,7 +82,7 @@ uvx authsome login <provider> [OPTIONS]
 | `--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. |
+| `--force` | Overwrite an existing connection without prompting. |
 
 Examples:
 
@@ -84,7 +95,7 @@ uvx authsome login github --base-url https://github.acme.com   # GitHub Enterpri
 ```
 
 <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.
+  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>
 
 ### `get`
@@ -96,7 +107,7 @@ uvx authsome get <provider> [OPTIONS]
 | Option | Description |
 |--------|-------------|
 | `--connection <name>` | Connection name. Default: `default`. |
-| `--field <field>` | Return only a specific field. |
+| `--field <field>` | Return only the value of a specific field. |
 | `--show-secret` | Reveal encrypted secret values in output. |
 
 ```bash
@@ -114,14 +125,15 @@ uvx authsome export <provider> [OPTIONS]
 | Option | Description |
 |--------|-------------|
 | `--connection <name>` | Connection name. Default: `default`. |
-| `--format <fmt>` | Output format: `env` (default) or `json`. |
+| `--format <fmt>` | Output format: `env` (default), `shell`, or `json`. |
 
 ```bash
-uvx authsome export github --format env       # KEY=value lines
-uvx authsome export openai --format json      # JSON object
+uvx authsome export github --format env      # KEY=value lines
+uvx authsome export github --format shell    # export KEY=value (sourceable)
+uvx 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.
+Only the `access_token` (OAuth2) or `api_key` (API-key) is exported. Refresh tokens are never exposed — authsome handles refresh transparently.
 
 ### `run`
 
@@ -170,18 +182,27 @@ uvx authsome scan --import --connection ci  # import into a named connection
 
 `scan` does not support `--quiet`. Use `--json` for headless contexts.
 
-### `connection set-default`
+### `set-default`
 
 ```bash
-uvx authsome connection set-default <provider> <connection>
+uvx 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.
 
 ```bash
-uvx authsome connection set-default github work
+uvx authsome set-default github work
 ```
 
+### `profile`
+
+```bash
+uvx authsome profile create   # create a new local profile keypair
+uvx 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](/concepts/profiles-vs-connections) for the distinction.
+
 ### `ui`
 
 ```bash
@@ -205,7 +226,7 @@ uvx authsome daemon logs [-n 100]
 
 - `serve` runs the daemon in the foreground (blocks the terminal).
 - `start` / `stop` / `restart` manage a background daemon.
-- `status` prints PID, base URL, and uptime.
+- `status` prints health, PID file path, and log file path as JSON.
 - `logs` tails the daemon log file.
 
 ### `logout` / `revoke` / `remove`
@@ -214,7 +235,7 @@ uvx authsome daemon logs [-n 100]
 |---------|-------------|-----------------|
 | `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 (bundled) | Not contacted |
+| `remove` | Removes the provider entirely (custom) or resets to bundled default (bundled) | Not contacted |
 
 ```bash
 uvx authsome logout github --connection work
@@ -225,35 +246,53 @@ uvx authsome remove acmecrm
 ### `register`
 
 ```bash
-uvx authsome register <path/to/provider.json> [--yes] [--force]
+uvx authsome register <path/to/provider.json> [OPTIONS]
 ```
 
-Validates the JSON, copies it into `~/.authsome/providers/`, and confirms the new provider appears in `authsome list`. Use `--yes` to skip the confirmation prompt in scripts, and `--force` to overwrite an existing provider with the same name.
+| 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`.
+
+```bash
+uvx authsome register ./acme.json             # prompt before registering
+uvx authsome register ./acme.json --force     # overwrite existing, no prompt
+uvx authsome register ./acme.json --yes       # skip prompt, fail if already exists
+```
 
 See [Custom providers](/guides/custom-providers) for full templates.
 
 ### `log`
 
 ```bash
-uvx authsome log              # last 50 audit entries
-uvx authsome log -n 200       # last 200
-uvx authsome log --json       # one JSON object per line, parsed
+uvx authsome log              # last 50 structured audit entries
+uvx authsome log -n 200       # last 200 entries
+uvx authsome log --json       # entries as a parsed JSON array
+uvx authsome log --raw        # raw client debug log (loguru format)
+uvx authsome log --raw -n 20  # last 20 lines of the client debug log
 ```
 
-Reads from `~/.authsome/audit.log`. Each entry records actions like `login`, `logout`, `revoke`, `export`, and `get --show-secret`.
+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 |
-|------|---------|
-| `0` | Success |
-| `1` | Generic failure |
-| `2` | Invalid usage |
-| `3` | Provider not found |
-| `4` | Authentication failed |
-| `5` | Credential missing |
-| `6` | Refresh failed |
-| `7` | Store unavailable |
-| `8` | User cancelled credential entry |
-
-When `--json` is passed and a command fails, the structured output includes an `error` and `message` key on stderr-friendly format.
+| 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.

{authsome-0.3.0 → authsome-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "authsome"
-version = "0.3.0"
+version = "0.3.1"
 description = "A portable local authentication library for AI agents and developer tools"
 readme = "README.md"
 license = "MIT"

{authsome-0.3.0 → authsome-0.3.1}/src/authsome/cli/context.py

@@ -56,6 +56,12 @@ class ContextObj:
             color = None
         click.secho(message, err=err, fg=color, nl=nl)
 
+    def emit(self, message: str, color: str | None = None, nl: bool = True) -> None:
+        """Print primary data output. Never suppressed by --quiet; respects --no-color."""
+        if self.no_color:
+            color = None
+        click.secho(message, fg=color, nl=nl)
+
 
 pass_ctx = click.make_pass_decorator(ContextObj)