bashboy 0.1.0__tar.gz → 0.2.1__tar.gz

{bashboy-0.1.0 → bashboy-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bashboy
-Version: 0.1.0
+Version: 0.2.1
 Summary: Classify shell commands as allow or deny before an agent runs them.
 Project-URL: Homepage, https://github.com/Mann10/bashboy
 Project-URL: Issues, https://github.com/Mann10/bashboy/issues
@@ -17,6 +17,10 @@ Description-Content-Type: text/markdown
 
 # BashBoy
 
+[![PyPI](https://img.shields.io/pypi/v/bashboy.svg)](https://pypi.org/project/bashboy/)
+[![Python](https://img.shields.io/pypi/pyversions/bashboy.svg)](https://pypi.org/project/bashboy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 BashBoy is a small, dependency-free Python CLI that classifies a shell command as
 `allow` or `deny` **before** a coding agent runs it. It sits in front of Claude Code
 (`PreToolUse` hook) and OpenCode (plugin) and answers one question: is this command
@@ -40,14 +44,22 @@ cannot answer clearly becomes `deny`.
 
 ## Install
 
-Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended; `pipx` works too).
 
 ```bash
-uv tool install bashboy     # install once
+uv tool install bashboy     # install the `bashboy` command
 uvx bashboy --help          # or run without installing
+pipx install bashboy        # pipx alternative
+```
+
+Verify the install:
+
+```bash
+bashboy version             # bashboy 0.2.0
+bashboy selftest            # offline checks; reports provider: ok when the key works
 ```
 
-From a local checkout (uvx resolves the project from the path):
+From a local checkout (for development, before a release is published):
 
 ```bash
 uvx --from /path/to/BashBoy bashboy check --command "git status"
@@ -57,14 +69,63 @@ uvx --from /path/to/BashBoy bashboy install --claude
 The package has **zero runtime dependencies** — everything is the Python standard
 library. `pytest` is a development-only dependency.
 
-The API key is read from the environment (default `CLOCKED_API_KEY`). It is never
-written to disk:
+### API key
+
+The token is resolved at call time; the first hit wins:
+
+| # | Source | Notes |
+|---|--------|-------|
+| 1 | `CLOCKED_API_KEY` (or the variable named by `[provider].api_key_env`) | Process environment; wins over everything |
+| 2 | `BASHBOY_API_KEY_FILE` | Full path to a credential file |
+| 3 | `[provider].api_key_file` in `config.toml` | `~` is expanded |
+| 4 | `~/.bashboy/credentials` | Default per-user file |
+| 5 | nothing | Model-path calls fail closed (`deny`, `source: "fallback"`) |
+
+GUI-launched hosts (Claude Code desktop, OpenCode's background service) do not
+inherit a shell profile, so a variable exported in a terminal is invisible to
+them. `setx` fixes that by exposing the key to every process on the machine. A
+per-user credential file is the middle ground: one host-agnostic location, no
+machine-wide secret, and rotation is a single file write.
 
 ```bash
-export CLOCKED_API_KEY=...        # bash
-$env:CLOCKED_API_KEY = "..."      # PowerShell
+bashboy auth set                    # prompt twice; input is never echoed
+bashboy auth status                 # path, source, presence, permissions
+bashboy auth status --check         # + one live provider call
+bashboy auth clear                  # delete after confirmation
+
+# provisioning / CI
+echo "$CLOCKED_API_KEY" | bashboy auth set --stdin --force
+```
+
+On Windows, `getpass` reads raw keystrokes with echo off, and pasting into that
+prompt is unreliable — Ctrl+V can land nothing or drop characters. If the
+prompt seems to ignore your paste, put the key on the clipboard and pipe it
+instead (it never touches shell history):
+
+```powershell
+Get-Clipboard | bashboy auth set --stdin --force
 ```
 
+`auth set` writes the file atomically, creates `~/.bashboy` with mode `0700` on
+POSIX, and sets the file itself to `0600`. The token is never accepted as a
+command-line argument — it would land in shell history and process listings — and
+it is never printed, logged, or stored in `config.toml` (which is shareable and
+gets pasted into issues). `auth status` never prints the value and makes no
+network call unless you pass `--check`.
+
+Permission policy:
+
+- **POSIX:** any group/other permission bit (`mode & 0o077`) is refused with a
+  message naming `chmod 600 <path>`, and the model path fails closed. Failing
+  closed beats silently consuming a leaked secret.
+- **Windows:** the file lives under your user profile, whose default ACL is
+  owner-only. `bashboy auth status` inspects the ACL with `icacls` and reports
+  any extra principals; it warns but still uses the key, because inherited
+  entries are normal. The ACL probe never runs on the `bashboy check` hot path.
+
+The token is read from the file at call time, so rotating it needs no host
+restart. A missing or empty file simply means "no key".
+
 ## Quick start
 
 ```bash
@@ -75,7 +136,7 @@ bashboy check --command "git status"
 # allow (allowlist): matches allowlist: git status
 
 bashboy check --command "docker run --rm alpine sh" --json
-# {"decision": "deny", "source": "fallback", "reason": "classifier unavailable: no API key ...", ...}
+# {"decision": "deny", "source": "fallback", "reason": "classifier unavailable: no API key configured (set CLOCKED_API_KEY or run `bashboy auth set`)", ...}
 ```
 
 Exit codes:
@@ -106,6 +167,7 @@ A missing file means these defaults:
 [provider]
 endpoint = "https://clocked.rezolve.ai/clocked/fill"
 api_key_env = "CLOCKED_API_KEY"
+api_key_file = "~/.bashboy/credentials"
 timeout_ms = 4000
 
 [policy]
@@ -128,6 +190,7 @@ loosens because a file failed to parse.
 | `BASHBOY_CONFIG` | Path to the config file (default `~/.bashboy/config.toml`) |
 | `BASHBOY_ENDPOINT` | Overrides `[provider].endpoint` |
 | `BASHBOY_API_KEY_ENV` | Name of the environment variable holding the key |
+| `BASHBOY_API_KEY_FILE` | Path to the credential file; overrides `[provider].api_key_file` |
 | `BASHBOY_FAIL_MODE` | `closed` (default) or `open`; anything else is an error |
 | `BASHBOY_DISABLE` | `1`/`true`/`yes` disables **all** checks (see below) |
 | `BASHBOY_DEBUG` | `1`/`true`/`yes` writes diagnostics to stderr only |
@@ -177,8 +240,9 @@ bashboy install --claude --from /path/to/BashBoy
 
 `--from SPEC` rewrites the argv to
 `["--from", SPEC, "bashboy", "check", "--claude-hook"]`, so `uvx` runs the given
-local checkout. The path is written verbatim as a single argv element — never
-interpolated into a shell string.
+local checkout. Use it only for a checkout or an unreleased build; a normal
+published install needs no `--from`. The path is written verbatim as a single
+argv element — never interpolated into a shell string.
 
 The hook reads one JSON object on stdin. On `deny` it prints the
 `hookSpecificOutput` envelope with `permissionDecision: "deny"`; on `allow`, blank
@@ -242,8 +306,9 @@ Nothing else is transmitted; no files are uploaded.
 
 Fast-path verdicts (`denylist`, `allowlist`, `disabled`) never leave the machine.
 There is no analytics, no audit log, no cache, and no telemetry. The API key is
-read from the environment at call time, sent only as the `Authorization` header,
-and never logged, persisted, or included in `config show`.
+read at call time from the environment or the credential file, sent only as the
+`Authorization` header, and never logged, persisted in `config.toml`, or included
+in `config show`.
 
 ## Known limitation: unverified Clocked envelope
 
@@ -283,8 +348,9 @@ Layout:
 
 ```
 src/bashboy/
-  cli.py            check / install / config / selftest / version
-  config.py         TOML defaults, env overrides, API key lookup
+  cli.py            check / install / config / auth / selftest / version
+  config.py         TOML defaults, env overrides, API key resolution
+  credentials.py    credential file read/write/clear + permission checks
   rules.py          structural allowlist + hard denylist (pure)
   provider.py       Clocked client, tolerant envelope parser
   classify.py       verdict pipeline (fast paths -> model -> fail closed)

{bashboy-0.1.0 → bashboy-0.2.1}/README.md

@@ -1,5 +1,9 @@
 # BashBoy
 
+[![PyPI](https://img.shields.io/pypi/v/bashboy.svg)](https://pypi.org/project/bashboy/)
+[![Python](https://img.shields.io/pypi/pyversions/bashboy.svg)](https://pypi.org/project/bashboy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 BashBoy is a small, dependency-free Python CLI that classifies a shell command as
 `allow` or `deny` **before** a coding agent runs it. It sits in front of Claude Code
 (`PreToolUse` hook) and OpenCode (plugin) and answers one question: is this command
@@ -23,14 +27,22 @@ cannot answer clearly becomes `deny`.
 
 ## Install
 
-Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended; `pipx` works too).
 
 ```bash
-uv tool install bashboy     # install once
+uv tool install bashboy     # install the `bashboy` command
 uvx bashboy --help          # or run without installing
+pipx install bashboy        # pipx alternative
+```
+
+Verify the install:
+
+```bash
+bashboy version             # bashboy 0.2.0
+bashboy selftest            # offline checks; reports provider: ok when the key works
 ```
 
-From a local checkout (uvx resolves the project from the path):
+From a local checkout (for development, before a release is published):
 
 ```bash
 uvx --from /path/to/BashBoy bashboy check --command "git status"
@@ -40,14 +52,63 @@ uvx --from /path/to/BashBoy bashboy install --claude
 The package has **zero runtime dependencies** — everything is the Python standard
 library. `pytest` is a development-only dependency.
 
-The API key is read from the environment (default `CLOCKED_API_KEY`). It is never
-written to disk:
+### API key
+
+The token is resolved at call time; the first hit wins:
+
+| # | Source | Notes |
+|---|--------|-------|
+| 1 | `CLOCKED_API_KEY` (or the variable named by `[provider].api_key_env`) | Process environment; wins over everything |
+| 2 | `BASHBOY_API_KEY_FILE` | Full path to a credential file |
+| 3 | `[provider].api_key_file` in `config.toml` | `~` is expanded |
+| 4 | `~/.bashboy/credentials` | Default per-user file |
+| 5 | nothing | Model-path calls fail closed (`deny`, `source: "fallback"`) |
+
+GUI-launched hosts (Claude Code desktop, OpenCode's background service) do not
+inherit a shell profile, so a variable exported in a terminal is invisible to
+them. `setx` fixes that by exposing the key to every process on the machine. A
+per-user credential file is the middle ground: one host-agnostic location, no
+machine-wide secret, and rotation is a single file write.
 
 ```bash
-export CLOCKED_API_KEY=...        # bash
-$env:CLOCKED_API_KEY = "..."      # PowerShell
+bashboy auth set                    # prompt twice; input is never echoed
+bashboy auth status                 # path, source, presence, permissions
+bashboy auth status --check         # + one live provider call
+bashboy auth clear                  # delete after confirmation
+
+# provisioning / CI
+echo "$CLOCKED_API_KEY" | bashboy auth set --stdin --force
+```
+
+On Windows, `getpass` reads raw keystrokes with echo off, and pasting into that
+prompt is unreliable — Ctrl+V can land nothing or drop characters. If the
+prompt seems to ignore your paste, put the key on the clipboard and pipe it
+instead (it never touches shell history):
+
+```powershell
+Get-Clipboard | bashboy auth set --stdin --force
 ```
 
+`auth set` writes the file atomically, creates `~/.bashboy` with mode `0700` on
+POSIX, and sets the file itself to `0600`. The token is never accepted as a
+command-line argument — it would land in shell history and process listings — and
+it is never printed, logged, or stored in `config.toml` (which is shareable and
+gets pasted into issues). `auth status` never prints the value and makes no
+network call unless you pass `--check`.
+
+Permission policy:
+
+- **POSIX:** any group/other permission bit (`mode & 0o077`) is refused with a
+  message naming `chmod 600 <path>`, and the model path fails closed. Failing
+  closed beats silently consuming a leaked secret.
+- **Windows:** the file lives under your user profile, whose default ACL is
+  owner-only. `bashboy auth status` inspects the ACL with `icacls` and reports
+  any extra principals; it warns but still uses the key, because inherited
+  entries are normal. The ACL probe never runs on the `bashboy check` hot path.
+
+The token is read from the file at call time, so rotating it needs no host
+restart. A missing or empty file simply means "no key".
+
 ## Quick start
 
 ```bash
@@ -58,7 +119,7 @@ bashboy check --command "git status"
 # allow (allowlist): matches allowlist: git status
 
 bashboy check --command "docker run --rm alpine sh" --json
-# {"decision": "deny", "source": "fallback", "reason": "classifier unavailable: no API key ...", ...}
+# {"decision": "deny", "source": "fallback", "reason": "classifier unavailable: no API key configured (set CLOCKED_API_KEY or run `bashboy auth set`)", ...}
 ```
 
 Exit codes:
@@ -89,6 +150,7 @@ A missing file means these defaults:
 [provider]
 endpoint = "https://clocked.rezolve.ai/clocked/fill"
 api_key_env = "CLOCKED_API_KEY"
+api_key_file = "~/.bashboy/credentials"
 timeout_ms = 4000
 
 [policy]
@@ -111,6 +173,7 @@ loosens because a file failed to parse.
 | `BASHBOY_CONFIG` | Path to the config file (default `~/.bashboy/config.toml`) |
 | `BASHBOY_ENDPOINT` | Overrides `[provider].endpoint` |
 | `BASHBOY_API_KEY_ENV` | Name of the environment variable holding the key |
+| `BASHBOY_API_KEY_FILE` | Path to the credential file; overrides `[provider].api_key_file` |
 | `BASHBOY_FAIL_MODE` | `closed` (default) or `open`; anything else is an error |
 | `BASHBOY_DISABLE` | `1`/`true`/`yes` disables **all** checks (see below) |
 | `BASHBOY_DEBUG` | `1`/`true`/`yes` writes diagnostics to stderr only |
@@ -160,8 +223,9 @@ bashboy install --claude --from /path/to/BashBoy
 
 `--from SPEC` rewrites the argv to
 `["--from", SPEC, "bashboy", "check", "--claude-hook"]`, so `uvx` runs the given
-local checkout. The path is written verbatim as a single argv element — never
-interpolated into a shell string.
+local checkout. Use it only for a checkout or an unreleased build; a normal
+published install needs no `--from`. The path is written verbatim as a single
+argv element — never interpolated into a shell string.
 
 The hook reads one JSON object on stdin. On `deny` it prints the
 `hookSpecificOutput` envelope with `permissionDecision: "deny"`; on `allow`, blank
@@ -225,8 +289,9 @@ Nothing else is transmitted; no files are uploaded.
 
 Fast-path verdicts (`denylist`, `allowlist`, `disabled`) never leave the machine.
 There is no analytics, no audit log, no cache, and no telemetry. The API key is
-read from the environment at call time, sent only as the `Authorization` header,
-and never logged, persisted, or included in `config show`.
+read at call time from the environment or the credential file, sent only as the
+`Authorization` header, and never logged, persisted in `config.toml`, or included
+in `config show`.
 
 ## Known limitation: unverified Clocked envelope
 
@@ -266,8 +331,9 @@ Layout:
 
 ```
 src/bashboy/
-  cli.py            check / install / config / selftest / version
-  config.py         TOML defaults, env overrides, API key lookup
+  cli.py            check / install / config / auth / selftest / version
+  config.py         TOML defaults, env overrides, API key resolution
+  credentials.py    credential file read/write/clear + permission checks
   rules.py          structural allowlist + hard denylist (pure)
   provider.py       Clocked client, tolerant envelope parser
   classify.py       verdict pipeline (fast paths -> model -> fail closed)

{bashboy-0.1.0 → bashboy-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bashboy"
-version = "0.1.0"
+version = "0.2.1"
 description = "Classify shell commands as allow or deny before an agent runs them."
 readme = "README.md"
 requires-python = ">=3.10"

{bashboy-0.1.0 → bashboy-0.2.1}/src/bashboy/__init__.py

@@ -1,5 +1,5 @@
 """BashBoy: a deny-only shell-command gate for coding agents."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = ["__version__"]

{bashboy-0.1.0 → bashboy-0.2.1}/src/bashboy/classify.py

@@ -19,7 +19,7 @@ import sys
 import time
 from dataclasses import dataclass
 
-from .config import Config, api_key, load_config
+from .config import Config, load_config, resolve_api_key
 from .rules import check_allowlist, check_denylist
 
 _TRUTHY = frozenset({"1", "true", "yes"})
@@ -105,7 +105,9 @@ def classify_command(
 
     target_cwd = cwd or os.getcwd()
     try:
-        model = provider if provider is not None else Provider(cfg.provider, key=api_key(cfg))
+        key, key_source = resolve_api_key(cfg)
+        log(f"api key source: {key_source}")  # source label only -- never the token
+        model = provider if provider is not None else Provider(cfg.provider, key=key)
         verdict = model.classify(target_cwd, command)  # type: ignore[attr-defined]
     except Exception as exc:  # noqa: BLE001 - every failure must map to a verdict
         fail_open = cfg.policy.fail_mode == "open"

{bashboy-0.1.0 → bashboy-0.2.1}/src/bashboy/cli.py

@@ -7,10 +7,12 @@ JSON in dry-run mode. Diagnostics go to stderr so ``| jq`` and hooks stay clean.
 from __future__ import annotations
 
 import argparse
+import dataclasses
 import json
 import os
 import platform
 import sys
+from getpass import getpass as _getpass
 from pathlib import Path
 
 from . import __version__
@@ -22,6 +24,15 @@ from .config import (
     api_key,
     config_path,
     load_config,
+    resolve_api_key,
+)
+from .credentials import (
+    CredentialError,
+    CredentialExistsError,
+    CredentialPermissionError,
+    clear_token,
+    permissions,
+    write_token,
 )
 
 
@@ -29,12 +40,17 @@ def _toml_bool(value: bool) -> str:
     return "true" if value else "false"
 
 
+def _toml_string(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
 def render_config(cfg: Config) -> str:
     lines = [
         f"# source: {cfg.path}",
         "[provider]",
         f'endpoint = "{cfg.provider.endpoint}"',
         f'api_key_env = "{cfg.provider.api_key_env}"',
+        f"api_key_file = {_toml_string(str(cfg.provider.api_key_file))}",
         f"timeout_ms = {cfg.provider.timeout_ms}",
         "",
         "[policy]",
@@ -102,6 +118,142 @@ def _cmd_config(args: argparse.Namespace) -> int:
     return 2
 
 
+# --- auth -----------------------------------------------------------------
+
+
+def _credential_target(args: argparse.Namespace, cfg: Config) -> Path:
+    override = getattr(args, "file", None)
+    if override:
+        return Path(override).expanduser().resolve()
+    return cfg.provider.api_key_file
+
+
+def _cmd_auth(args: argparse.Namespace) -> int:
+    print(
+        "usage: bashboy auth {set,status,clear} ... (see `bashboy auth --help`)",
+        file=sys.stderr,
+    )
+    return 2
+
+
+def _cmd_auth_set(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    path = _credential_target(args, cfg)
+
+    if args.stdin:
+        token = sys.stdin.read().strip()
+    else:
+        token = _getpass("Clocked API key (input hidden): ").strip()
+        if token:
+            confirm = _getpass("Repeat to confirm (input hidden): ").strip()
+            if confirm != token:
+                print("bashboy: tokens did not match", file=sys.stderr)
+                return 2
+    if not token:
+        print("bashboy: no token provided", file=sys.stderr)
+        return 2
+
+    try:
+        write_token(path, token, overwrite=args.force)
+    except CredentialExistsError as exc:
+        print(f"bashboy: {exc}", file=sys.stderr)
+        return 1
+    except (CredentialError, OSError) as exc:
+        print(f"bashboy: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"saved {path}")
+    print(f"permissions: {permissions(path).detail}")
+
+    if os.environ.get(cfg.provider.api_key_env, "").strip():
+        print(
+            f"note: {cfg.provider.api_key_env} is set and takes precedence over the file",
+            file=sys.stderr,
+        )
+
+    from .provider import verify_key  # lazy: keeps `bashboy --help` fast
+
+    try:
+        verdict = verify_key(cfg.provider, token)
+    except Exception as exc:  # noqa: BLE001 - reported, never fatal
+        print(f"provider: FAILED ({exc})")
+        return 2
+    print(f"provider: ok ({verdict.decision})")
+    return 0
+
+
+def _cmd_auth_status(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    path = _credential_target(args, cfg)
+    if path != cfg.provider.api_key_file:
+        # `--file` must drive resolution too, not just the reported path.
+        cfg = dataclasses.replace(
+            cfg, provider=dataclasses.replace(cfg.provider, api_key_file=path)
+        )
+    # The only place the Windows ACL is probed: never on the `check` hot path.
+    state = permissions(path, probe_acl=True)
+
+    print(f"config: {cfg.path}")
+    print(f"endpoint: {cfg.provider.endpoint}")
+    print(f"credential file: {path}")
+    print(f"permissions: {state.detail}")
+    if state.label == "extra-principals":
+        log(f"credential file ACL: {state.detail}")
+
+    try:
+        key, source = resolve_api_key(cfg)
+    except CredentialPermissionError as exc:
+        key, source = None, f"refused ({exc})"
+    except CredentialError as exc:
+        key, source = None, f"unreadable ({exc})"
+    if key and state.label in {"extra-principals", "unverified"}:
+        # The probe above is more specific than the hot-path label in `source`.
+        source = f"file {path} ({state.label})"
+    print(f"key source: {source}")
+    if key:
+        print("key: present")
+    elif source.startswith(("refused", "unreadable")):
+        print("key: refused")
+    else:
+        print("key: absent")
+
+    if args.check:
+        if key:
+            from .provider import verify_key  # lazy: opt-in network call only
+
+            try:
+                verdict = verify_key(cfg.provider, key)
+            except Exception as exc:  # noqa: BLE001 - reported, never fatal
+                print(f"provider: FAILED ({exc})")
+            else:
+                print(f"provider: ok ({verdict.decision})")
+        else:
+            print("provider: skipped (no API key)")
+    return 0
+
+
+def _cmd_auth_clear(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    path = _credential_target(args, cfg)
+    if not path.is_file():
+        print(f"no credential file at {path}")
+        return 0
+
+    if not args.force:
+        answer = input(f"delete {path}? [y/N] ")
+        if answer.strip().lower() not in {"y", "yes"}:
+            print("aborted")
+            return 1
+
+    try:
+        clear_token(path)
+    except OSError as exc:
+        print(f"bashboy: {exc}", file=sys.stderr)
+        return 2
+    print(f"removed {path}")
+    return 0
+
+
 # --- install --------------------------------------------------------------
 
 _DEFAULT_CLAUDE_SETTINGS = Path.home() / ".claude" / "settings.json"
@@ -241,6 +393,26 @@ def _build_parser() -> argparse.ArgumentParser:
     config.add_argument("--force", action="store_true", help="overwrite an existing config")
     config.set_defaults(handler=_cmd_config)
 
+    auth = sub.add_parser("auth", help="manage the Clocked API key file")
+    auth.set_defaults(handler=_cmd_auth)
+    auth_sub = auth.add_subparsers(dest="auth_action")
+
+    auth_set = auth_sub.add_parser("set", help="save the API key to the credential file")
+    auth_set.add_argument("--file", default=None, help="credential file path")
+    auth_set.add_argument("--stdin", action="store_true", help="read the key from stdin")
+    auth_set.add_argument("--force", action="store_true", help="overwrite an existing file")
+    auth_set.set_defaults(handler=_cmd_auth_set)
+
+    auth_status = auth_sub.add_parser("status", help="show the key source and file permissions")
+    auth_status.add_argument("--file", default=None, help="credential file path")
+    auth_status.add_argument("--check", action="store_true", help="make one live provider call")
+    auth_status.set_defaults(handler=_cmd_auth_status)
+
+    auth_clear = auth_sub.add_parser("clear", help="delete the credential file")
+    auth_clear.add_argument("--file", default=None, help="credential file path")
+    auth_clear.add_argument("--force", action="store_true", help="skip the confirmation prompt")
+    auth_clear.set_defaults(handler=_cmd_auth_clear)
+
     selftest = sub.add_parser("selftest", help="run offline self-checks")
     selftest.set_defaults(handler=_cmd_selftest)
 
@@ -259,7 +431,7 @@ def main(argv: list[str] | None = None) -> int:
         return 2
     try:
         return int(handler(args))
-    except ConfigError as exc:
+    except (ConfigError, CredentialError) as exc:
         print(f"bashboy: {exc}", file=sys.stderr)
         return 2
     except KeyboardInterrupt:  # pragma: no cover - interactive only