navigator-cli 0.1.0__tar.gz

navigator_cli-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: navigator-cli
+Version: 0.1.0
+Summary: Navigator CLI + Data Navigator service: query public data sources from your agent
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: keyring<26,>=25
+Requires-Dist: markdown>=3.10.2
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"

navigator_cli-0.1.0/README.md

@@ -0,0 +1,141 @@
+# Data Navigator
+
+Members-only catalogue of skill files that teach AI agents to query public
+databases, plus the executor that runs the queries. Three faces — web UI, the
+`navigator` CLI, and (Phase 3) MCP — all over one HTTP API. See `SPEC.md` for
+the full design; this README covers running and validating the local app.
+
+## Layout
+
+The skill tree is the single source of truth:
+
+```text
+skills/<jurisdiction>/<source-slug>/
+├── SKILL.md     # agent-facing playbook: inputs, output shape, gotchas
+├── meta.yaml    # validated catalogue record (app/skills_registry.py)
+└── adapter.py   # run(input, ctx) — executes the query
+```
+
+- `skills/_template/` — copy this to add a source; every field is documented.
+- `skills/_meta/navigator-data/` — the meta-skill members drop into
+  `~/.claude/skills/` so their agent knows the find → show → query loop.
+- `app/skills_registry.py` — walks the tree, validates every `meta.yaml`
+  (pydantic), builds the registry. Invalid skill dirs fail the app at startup.
+- `app/runner.py` — dynamic adapter loading + `AdapterContext.get_key()`
+  (OS keychain / `NAVIGATOR_KEY_<NAME>` env; keys never enter agent context).
+
+Source runtimes: `local` (public or BYO-key, runs on the member's machine,
+unmetered) and `hosted` (our key, runs server-side, metered — e.g.
+OpenSanctions).
+
+## Run locally
+
+```bash
+uv sync --extra test
+uv run uvicorn app.main:app --reload --port 8000
+```
+
+Open `http://localhost:8000/data`. Set `OPENROUTER_API_KEY` to enable the
+natural-language query bar (`/api/query/natural` returns 503 without it —
+there is no fallback planner).
+
+## Run with Docker
+
+```bash
+docker compose up --build
+```
+
+## CLI
+
+One unified `navigator` CLI for the whole product: `navigator data …` is Data
+Navigator, `navigator tools …` (Phase 3) is osint-navigator.
+
+```bash
+navigator auth login                   # magic link → PAT in the OS keychain
+navigator auth status                  # tier + quota state
+navigator data find company            # search the catalogue
+navigator data show no/brreg/enheter   # print the source's SKILL.md + meta
+navigator query no/brreg/enheter --input '{"navn":"Equinor","size":3}'
+navigator query no/brreg/enheter --input '{"navn":"Equinor"}' --out companies.csv
+navigator tools find "satellite imagery"   # OSINT tool search (osint-navigator API)
+navigator tools show <tool-id>             # full tool record + documentation
+navigator keys missing                 # BYO keys you still need to set
+navigator keys set companies-house     # store a key in the OS keychain
+```
+
+`--out <file>.json|.csv` writes the records to the file and prints a compact
+summary instead of the full payload. Hosted sources route to the Data
+Navigator server (`DATANAV_BASE_URL`) with the stored PAT.
+
+There is no install step: with `DATANAV_CATALOGUE=remote` the CLI fetches
+skill bundles from the authed API and caches them under `~/.navigator/cache/`
+(re-fetched when a source's meta changes). Default is `local` (this checkout)
+for dev and smoke tests. The only thing a member installs is the meta-skill.
+
+## Membership (Phase 2)
+
+Everything is member-gated in production (`DATANAV_AUTH=on`; default off for
+local dev). Auth is owned by osint-navigator — this service validates Bearer
+PATs / the shared `osint_session` cookie via its internal introspection API
+and requires the `data` tier (above osint pro). Metering: UI NL queries +
+try-it burn `data_ui`; hosted-source queries burn `data_hosted`; public + BYO
+local execution is never metered. Quota storage lives in osint-navigator.
+
+Cross-service proof: `uv run python scripts/integration_check_membership.py`
+(boots osint-navigator's internal API from the sibling checkout and verifies
+401/403/tier/quota behavior end-to-end).
+
+## MCP, meta-skill, rollout
+
+- **MCP**: `data_find_source` / `data_show_source` / `data_query` live on
+  osint-navigator's remote MCP and proxy here over the service channel. Local
+  sources are unmetered over MCP (the member's agent reasons; upstream is free).
+- **Meta-skill**: members download it from the UI ("Agent setup") or
+  `GET /api/meta-skill` and drop it into `~/.claude/skills/navigator-data/`.
+- **Rollout**: the Data toggle in osint-navigator's header is admin-only
+  (`ADMIN_EMAILS` web sessions) until launch; `/data` is reverse-proxied from
+  osint-navigator when `DATA_NAVIGATOR_URL` is set.
+- **Deploy**: operator steps in `docs/deploy/phase2-deploy-runbook.html`.
+
+## API
+
+```bash
+curl -s "http://localhost:8000/api/registry"
+curl -s "http://localhost:8000/api/sources/no/brreg/enheter"   # meta + skill_md
+curl -s -X POST "http://localhost:8000/api/query/no/brreg/enheter" \
+  -H "Content-Type: application/json" -d '{"navn":"Equinor","size":3}'
+```
+
+## Validation
+
+First, validate the skill tree (both smoke scripts assume this passes):
+
+```bash
+uv run python scripts/validate_skills.py
+```
+
+The validation gate is three live public APIs returning records:
+
+- `no/brreg/enheter` — Norway Brønnøysund companies
+- `us/usaspending/awards` — USAspending federal awards
+- `global/gleif/lei-records` — GLEIF LEI records
+
+```bash
+uv run pytest
+DATANAV_BASE_URL=http://localhost:8000 uv run python scripts/smoke_public_apis.py
+NAVIGATOR_CMD="uv run navigator" uv run python scripts/smoke_cli_public_apis.py
+bash scripts/smoke_docker_image.sh
+```
+
+## Deployment
+
+`render.yaml` defines a Docker web service (health check `/health`, port from
+`$PORT`). Server secrets: `OPENROUTER_API_KEY` (NL planner) and
+`NAVIGATOR_KEY_OPENSANCTIONS` (hosted OpenSanctions sources).
+
+Phase 2 (membership wiring: auth introspection against osint-navigator,
+metered quotas, submissions form) and Phase 3 (MCP, catalogue growth) are
+specified in `SPEC.md` §9.
+
+Spotlight integration is intentionally not implemented here — separate
+partner-reviewed PR after the OpenSanctions output contract is stable.

navigator_cli-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+"""Data Navigator local app."""

navigator_cli-0.1.0/app/catalogue_client.py

@@ -0,0 +1,127 @@
+"""Remote catalogue for the CLI: fetch-on-demand skills, cached locally.
+
+There is no install step. `find`/`show`/`query` pull the registry and skill
+bundles from the authed Data Navigator API and cache them under
+~/.navigator/cache/. A cached bundle is re-fetched when the registry entry's
+`last_tested` or meta content changes; offline, the stale cache is used with
+a warning on stderr.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+from app.cli_auth import get_pat
+from app.skills_registry import Source
+
+
+def cache_dir() -> Path:
+    return Path(os.getenv("NAVIGATOR_CACHE_DIR", str(Path.home() / ".navigator" / "cache")))
+
+
+def _base_url() -> str:
+    return os.getenv("DATANAV_BASE_URL", "https://navigator.indicator.media/data").rstrip("/")
+
+
+def _headers() -> dict:
+    pat = get_pat()
+    if not pat:
+        raise RuntimeError("Not logged in. Run: navigator auth login")
+    return {"Authorization": f"Bearer {pat}"}
+
+
+def _get(path: str) -> dict:
+    response = httpx.get(f"{_base_url()}{path}", headers=_headers(), timeout=30)
+    if response.status_code == 401:
+        raise RuntimeError("Session expired or invalid. Run: navigator auth login")
+    if response.status_code == 403:
+        detail = response.json().get("detail", {})
+        url = detail.get("upgrade_url", "") if isinstance(detail, dict) else ""
+        raise RuntimeError(f"Data Navigator membership required. {url}".strip())
+    response.raise_for_status()
+    return response.json()
+
+
+def _meta_fingerprint(meta: dict) -> str:
+    return hashlib.sha256(
+        json.dumps(meta, sort_keys=True, ensure_ascii=False).encode()
+    ).hexdigest()
+
+
+def fetch_registry() -> dict:
+    """Fetch the registry, falling back to the cached copy when offline."""
+    registry_path = cache_dir() / "registry.json"
+    try:
+        registry = _get("/api/registry")
+    except httpx.HTTPError as exc:
+        if registry_path.exists():
+            print(f"navigator: offline ({exc}); using cached catalogue", file=sys.stderr)
+            return json.loads(registry_path.read_text(encoding="utf-8"))
+        raise RuntimeError(f"Could not reach Data Navigator and no cache exists: {exc}") from exc
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+    registry_path.write_text(json.dumps(registry, ensure_ascii=False, indent=2), encoding="utf-8")
+    return registry
+
+
+def _bundle_dir(source_id: str) -> Path:
+    return cache_dir() / source_id.replace("/", "--")
+
+
+def fetch_bundle(source_id: str, meta: dict) -> Path:
+    """Ensure the skill bundle is cached and current; return its directory."""
+    target = _bundle_dir(source_id)
+    fingerprint_path = target / ".fingerprint"
+    fingerprint = _meta_fingerprint(meta)
+
+    if fingerprint_path.exists() and fingerprint_path.read_text() == fingerprint:
+        return target
+
+    try:
+        bundle = _get(f"/api/sources/{source_id}/bundle")
+    except httpx.HTTPError as exc:
+        if (target / "meta.json").exists():
+            print(f"navigator: offline ({exc}); using cached skill", file=sys.stderr)
+            return target
+        raise RuntimeError(f"Could not fetch skill bundle for {source_id}: {exc}") from exc
+
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "meta.json").write_text(
+        json.dumps(bundle["meta"], ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    (target / "SKILL.md").write_text(bundle["skill_md"], encoding="utf-8")
+    adapter = bundle.get("adapter_py")
+    adapter_path = target / "adapter.py"
+    if adapter:
+        adapter_path.write_text(adapter, encoding="utf-8")
+    elif adapter_path.exists():
+        adapter_path.unlink()
+    fingerprint_path.write_text(fingerprint)
+    return target
+
+
+def remote_catalogue() -> list[Source]:
+    """Registry entries as Source models. `dir` points at nothing yet —
+    it is bound to the cached bundle dir on demand by remote_source()."""
+    registry = fetch_registry()
+    sources = []
+    for entry in registry.get("sources", []):
+        data = {k: v for k, v in entry.items() if k != "queryable"}
+        sources.append(Source(**data))
+    return sources
+
+
+def remote_source(source_id: str) -> Source:
+    """Resolve one source with its cached bundle dir bound (for local execution)."""
+    registry = fetch_registry()
+    entry = next((s for s in registry.get("sources", []) if s["id"] == source_id), None)
+    if entry is None:
+        raise ValueError(f"Unknown source: {source_id}")
+    meta = {k: v for k, v in entry.items() if k != "queryable"}
+    source = Source(**meta)
+    source.dir = fetch_bundle(source_id, meta)
+    return source

navigator_cli-0.1.0/app/cli.py

@@ -0,0 +1,376 @@
+"""Agent-facing `navigator` CLI for Data Navigator."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+from getpass import getpass
+from pathlib import Path
+from typing import Any, Sequence
+
+import httpx
+
+from app import cli_auth
+from app.keys import KeyStoreError, key_state, navigator_env_var, set_key, unset_key
+from app.runner import MissingKeyError, execute
+from app.skills_registry import Source, load_sources, source_payload
+
+
+def _remote_mode() -> bool:
+    """remote = authed API + ~/.navigator/cache (members); local = repo checkout (dev)."""
+    return os.getenv("DATANAV_CATALOGUE", "local") == "remote"
+
+
+def _catalogue() -> list[Source]:
+    if _remote_mode():
+        from app.catalogue_client import remote_catalogue
+
+        return remote_catalogue()
+    return load_sources()
+
+
+def _get_source(source_id: str) -> Source:
+    if _remote_mode():
+        from app.catalogue_client import remote_source
+
+        return remote_source(source_id)
+    source = next((s for s in load_sources() if s.id == source_id), None)
+    if not source:
+        raise ValueError(f"Unknown source: {source_id}")
+    return source
+
+
+def _parse_json_input(raw: str) -> dict[str, Any]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"--input must be valid JSON: {exc.msg}") from exc
+    if not isinstance(value, dict):
+        raise ValueError("--input must be a JSON object")
+    return value
+
+
+def _print_json(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=False))
+
+
+def _print_sources(sources: list[Source], as_json: bool) -> None:
+    if as_json:
+        _print_json({"sources": [source_payload(s) for s in sources], "count": len(sources)})
+        return
+    for source in sources:
+        marker = "queryable" if source.queryable else source.status
+        print(f"{source.id}\t{marker}\t{source.title}")
+
+
+def _run_hosted_query(source: Source, payload: dict[str, Any]) -> dict[str, Any]:
+    base = os.getenv("DATANAV_BASE_URL", "http://localhost:8000").rstrip("/")
+    headers = {}
+    pat = cli_auth.get_pat()
+    if pat:
+        headers["Authorization"] = f"Bearer {pat}"
+    try:
+        response = httpx.post(
+            f"{base}/api/query/{source.id}", json=payload, headers=headers, timeout=60
+        )
+    except httpx.HTTPError as exc:
+        raise RuntimeError(f"Could not reach Data Navigator server at {base}: {exc}") from exc
+    if response.status_code == 401:
+        raise RuntimeError("Membership required for hosted sources. Run: navigator auth login")
+    if response.status_code >= 400:
+        try:
+            detail = response.json().get("detail")
+        except (json.JSONDecodeError, ValueError):
+            detail = response.text[:500]
+        raise RuntimeError(f"Server returned HTTP {response.status_code}: {detail}")
+    return response.json()
+
+
+def _run_query(source_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    source = _get_source(source_id)
+    if source.runtime == "hosted":
+        return _run_hosted_query(source, payload)
+    try:
+        return execute(source, payload)
+    except MissingKeyError as exc:
+        raise ValueError(str(exc)) from exc
+    except httpx.HTTPStatusError as exc:
+        raise RuntimeError(
+            f"Upstream returned HTTP {exc.response.status_code}: {exc.response.text[:500]}"
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise RuntimeError(f"Upstream request failed: {exc}") from exc
+
+
+def _write_out(result: dict, out: str) -> dict:
+    path = Path(out)
+    records = result.get("records", [])
+    if path.suffix == ".csv":
+        keys = sorted({k for r in records for k in r})
+        with path.open("w", newline="", encoding="utf-8") as fh:
+            writer = csv.DictWriter(fh, fieldnames=keys)
+            writer.writeheader()
+            for r in records:
+                writer.writerow(
+                    {k: (json.dumps(v) if isinstance(v, (dict, list)) else v) for k, v in r.items()}
+                )
+    else:
+        path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    return {
+        "source_id": result.get("source_id"),
+        "records": len(records),
+        "fields": sorted({k for r in records[:1] for k in r}),
+        "out": str(path),
+    }
+
+
+def _cmd_data_find(args: argparse.Namespace) -> int:
+    needle = " ".join(args.query).lower()
+    sources = _catalogue()
+    if needle:
+        sources = [
+            s
+            for s in sources
+            if needle
+            in " ".join([s.id, s.title, s.description, s.category, s.jurisdiction, s.notes]).lower()
+        ]
+    _print_sources(sources, args.json)
+    return 0
+
+
+def _cmd_data_show(args: argparse.Namespace) -> int:
+    source = _get_source(args.source_id)
+    skill_md = (source.dir / "SKILL.md").read_text(encoding="utf-8")
+    print(skill_md)
+    print("---")
+    _print_json(source_payload(source))
+    return 0
+
+
+def _cmd_query(args: argparse.Namespace) -> int:
+    payload = _parse_json_input(args.input)
+    result = _run_query(args.source_id, payload)
+    if getattr(args, "out", None):
+        _print_json(_write_out(result, args.out))
+    else:
+        _print_json(result)
+    return 0
+
+
+def _cmd_tools_find(args: argparse.Namespace) -> int:
+    from app.tools_client import find_tools
+
+    result = find_tools(" ".join(args.query), category=args.category, limit=args.limit)
+    if args.json:
+        _print_json(result)
+        return 0
+    for tool in result.get("tools", []):
+        print(f"{tool.get('tool_id')}\t{tool.get('tool_name')}\t{tool.get('tool_url')}")
+    return 0
+
+
+def _cmd_tools_show(args: argparse.Namespace) -> int:
+    from app.tools_client import show_tool
+
+    tool = show_tool(args.tool_id)
+    if args.json:
+        _print_json(tool)
+        return 0
+    print(f"# {tool.get('tool_name') or args.tool_id}")
+    for field in ("tool_url", "category", "pricing", "status"):
+        if tool.get(field):
+            print(f"{field}: {tool[field]}")
+    if tool.get("tags"):
+        print(f"tags: {', '.join(tool['tags'])}")
+    if tool.get("short_description"):
+        print(f"\n{tool['short_description']}")
+    if tool.get("documentation"):
+        print(f"\n{tool['documentation']}")
+    return 0
+
+
+def _cmd_auth_login(args: argparse.Namespace) -> int:
+    email = args.email or input("Email on your membership: ").strip()
+    if not email:
+        raise ValueError("email is required")
+    result = cli_auth.login(email)
+    _print_json(result)
+    return 0
+
+
+def _cmd_auth_status(args: argparse.Namespace) -> int:
+    _print_json(cli_auth.status())
+    return 0
+
+
+def _cmd_auth_logout(args: argparse.Namespace) -> int:
+    _print_json(cli_auth.logout())
+    return 0
+
+
+def _cmd_keys_missing(args: argparse.Namespace) -> int:
+    missing = []
+    for source in _catalogue():
+        if source.auth.type == "api_key" and source.auth.key_name:
+            state = key_state(source.auth.key_name)
+            if state.configured:
+                continue
+            missing.append(
+                {
+                    "source_id": source.id,
+                    "key_name": source.auth.key_name,
+                    "env_var": navigator_env_var(source.auth.key_name),
+                    "setup_url": source.auth.setup_url,
+                    "setup_help": source.auth.setup_help,
+                }
+            )
+    _print_json({"missing": missing, "count": len(missing)})
+    return 0
+
+
+def _configured_key_names() -> list[str]:
+    names = sorted(
+        {
+            source.auth.key_name
+            for source in _catalogue()
+            if source.auth.type == "api_key" and source.auth.key_name
+        }
+    )
+    return [name for name in names if name]
+
+
+def _cmd_keys_list(args: argparse.Namespace) -> int:
+    states = [key_state(name).__dict__ for name in _configured_key_names()]
+    _print_json({"keys": states, "count": len(states)})
+    return 0
+
+
+def _cmd_keys_set(args: argparse.Namespace) -> int:
+    value = sys.stdin.read().strip() if args.stdin else None
+    if value is None:
+        value = getpass(f"{args.name}: ")
+    set_key(args.name, value)
+    _print_json({"name": args.name, "stored": True, "source": "keyring"})
+    return 0
+
+
+def _cmd_keys_get(args: argparse.Namespace) -> int:
+    if not args.reveal:
+        raise ValueError("Refusing to reveal a key without --reveal")
+    from app.keys import get_key
+
+    value = get_key(args.name)
+    if not value:
+        raise ValueError(f"Key is not configured: {args.name}")
+    print(value)
+    return 0
+
+
+def _cmd_keys_unset(args: argparse.Namespace) -> int:
+    unset_key(args.name)
+    _print_json({"name": args.name, "deleted": True})
+    return 0
+
+
+def _add_query_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("source_id")
+    parser.add_argument("--input", required=True, help="JSON object input for the source adapter")
+    parser.add_argument(
+        "--out",
+        help="Write records to this file (.json or .csv) and print a compact summary",
+    )
+    parser.set_defaults(func=_cmd_query)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="navigator",
+        description="Navigator CLI — Data mode.",
+    )
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    data = subcommands.add_parser("data", help="Data Navigator commands")
+    data_subcommands = data.add_subparsers(dest="data_command", required=True)
+
+    data_find = data_subcommands.add_parser("find", help="Search the data-source catalogue")
+    data_find.add_argument("query", nargs="*", help="Search query")
+    data_find.add_argument("--json", action="store_true", help="Print full JSON payload")
+    data_find.set_defaults(func=_cmd_data_find)
+
+    data_show = data_subcommands.add_parser(
+        "show", help="Show one source: SKILL.md playbook followed by meta JSON"
+    )
+    data_show.add_argument("source_id")
+    data_show.set_defaults(func=_cmd_data_show)
+
+    data_query = data_subcommands.add_parser("query", help="Run a source query")
+    _add_query_arguments(data_query)
+
+    query = subcommands.add_parser("query", help="Universal agent-facing source query")
+    _add_query_arguments(query)
+
+    tools = subcommands.add_parser("tools", help="OSINT Navigator tool catalogue (thin API client)")
+    tools_subcommands = tools.add_subparsers(dest="tools_command", required=True)
+    tools_find = tools_subcommands.add_parser("find", help="Search OSINT tools by meaning")
+    tools_find.add_argument("query", nargs="+", help="Search query")
+    tools_find.add_argument("--category", help="Optional category filter")
+    tools_find.add_argument("--limit", type=int, default=10)
+    tools_find.add_argument("--json", action="store_true", help="Print full JSON payload")
+    tools_find.set_defaults(func=_cmd_tools_find)
+    tools_show = tools_subcommands.add_parser("show", help="Full record + documentation for one tool")
+    tools_show.add_argument("tool_id")
+    tools_show.add_argument("--json", action="store_true", help="Print full JSON payload")
+    tools_show.set_defaults(func=_cmd_tools_show)
+
+    auth = subcommands.add_parser("auth", help="Membership login for the Navigator CLI")
+    auth_subcommands = auth.add_subparsers(dest="auth_command", required=True)
+    auth_login = auth_subcommands.add_parser("login", help="Sign in via magic link; stores a PAT in the OS keychain")
+    auth_login.add_argument("email", nargs="?", help="Email on your membership")
+    auth_login.set_defaults(func=_cmd_auth_login)
+    auth_status = auth_subcommands.add_parser("status", help="Show login + quota state")
+    auth_status.set_defaults(func=_cmd_auth_status)
+    auth_logout = auth_subcommands.add_parser("logout", help="Remove the stored PAT")
+    auth_logout.set_defaults(func=_cmd_auth_logout)
+
+    keys = subcommands.add_parser("keys", help="BYO key helper commands")
+    keys_subcommands = keys.add_subparsers(dest="keys_command", required=True)
+    keys_list = keys_subcommands.add_parser("list", help="List BYO key configuration state")
+    keys_list.set_defaults(func=_cmd_keys_list)
+    keys_set = keys_subcommands.add_parser("set", help="Store a BYO API key in the OS keychain")
+    keys_set.add_argument("name")
+    keys_set.add_argument("--stdin", action="store_true", help="Read the secret value from stdin")
+    keys_set.set_defaults(func=_cmd_keys_set)
+    keys_get = keys_subcommands.add_parser("get", help="Reveal a configured BYO API key")
+    keys_get.add_argument("name")
+    keys_get.add_argument("--reveal", action="store_true", help="Required to print the secret")
+    keys_get.set_defaults(func=_cmd_keys_get)
+    keys_unset = keys_subcommands.add_parser("unset", help="Delete a BYO API key from the OS keychain")
+    keys_unset.add_argument("name")
+    keys_unset.set_defaults(func=_cmd_keys_unset)
+    keys_missing = keys_subcommands.add_parser("missing", help="List sources that require BYO keys")
+    keys_missing.set_defaults(func=_cmd_keys_missing)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except ValueError as exc:
+        print(f"navigator: {exc}", file=sys.stderr)
+        return 2
+    except KeyStoreError as exc:
+        print(f"navigator: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(f"navigator: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())