Refactor CLI dependencies and update documentation

CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-08-04
+
+### Changed
+
+- **Breaking for CLI users.** `typer` and `rich` moved out of the runtime
+  dependencies into a new `cli` extra. Only the CLI module imports them, but
+  declaring them at runtime forced `rich>=14` onto every project that merely
+  imported the client, which made pyonyphe unresolvable alongside pins such as
+  `censys==2.0.9` (`rich<11`).
+
+  Installing the library is unchanged. To get the `pyonyphe` command, install
+  the extra:
+
+  ```
+  uv add 'pyonyphe[cli]'
+  ```
+
+  Without it, importing `pyonyphe` still works; running `pyonyphe` fails with
+  `ModuleNotFoundError: typer`. The published container image is unaffected —
+  it installs the extra.
+
 ## [3.0.2] - 2026-08-04
 
 ### Fixed

Dockerfile

@@ -23,12 +23,14 @@ ENV UV_COMPILE_BYTECODE=1 \
 WORKDIR /app
 
 # Dependencies first: this layer is cached until pyproject.toml or uv.lock move.
+# --extra cli is required since 3.1.0: typer and rich moved out of the runtime
+# dependencies, and the image exists to ship the CLI.
 COPY pyproject.toml uv.lock ./
-RUN uv sync --frozen --no-dev --no-install-project
+RUN uv sync --frozen --no-dev --no-install-project --extra cli
 
 COPY README.md LICENSE ./
 COPY src ./src
-RUN uv sync --frozen --no-dev --no-editable
+RUN uv sync --frozen --no-dev --no-editable --extra cli
 
 
 FROM python:3.13-slim-bookworm

README.md

@@ -16,11 +16,22 @@ the Cyber Defense Search Engine.
 
 ## Install
 
+The library on its own:
+
 ```bash
 uv add pyonyphe
+```
+
+The `pyonyphe` command needs the `cli` extra, which pulls in Typer and Rich:
+
+```bash
+uv add 'pyonyphe[cli]'
 uv run pyonyphe --help
 ```
 
+Since 3.1.0 those two are no longer runtime dependencies, so importing the
+client no longer constrains `rich` in your own resolution.
+
 ## Library
 
 ```python
@@ -56,6 +67,8 @@ asyncio.run(main())
 
 ## CLI
 
+Needs `uv add 'pyonyphe[cli]'`, or use the container image below.
+
 ```bash
 export ONYPHE_API_KEY=...
 

pyproject.toml

@@ -31,12 +31,19 @@ dependencies = [
     "httpx>=0.28",
     "pydantic>=2.11",
     "python-dotenv>=1.1",
-    "rich>=14.0",
-    "typer>=0.16",
     "tomli>=2.0; python_version < '3.11'",
 ]
 
 [project.optional-dependencies]
+# Only `cli.py` imports typer and rich, so they do not belong to the library.
+# Declaring them at runtime imposed rich>=14 on every consumer, which collides
+# with pins such as censys==2.0.9 (rich<11) and made pyonyphe unresolvable in
+# projects that merely import the client. typer is here too because it pulls
+# rich in on its own.
+cli = [
+    "rich>=14.0",
+    "typer>=0.16",
+]
 # SDK v2: `FastMCP` became `MCPServer` and the import paths moved, so the
 # major is pinned rather than left open.
 mcp = ["mcp>=2,<3"]
@@ -64,6 +71,9 @@ dev = [
     "twine>=6.1",
     # The MCP extra, so the server is importable in the test suite.
     "mcp>=2,<3",
+    # The CLI extra, so the cli tests still run from a bare dev install.
+    "rich>=14.0",
+    "typer>=0.16",
     # Not needed at runtime on 3.11+, but ty analyses against 3.10 and has to
     # be able to resolve the fallback import in config.py.
     "tomli>=2.0",