# CLI-Hub Architecture for Autonomous CLI Discovery and Installation in CLI-Anything > Discover CLI-Hub's modular three-layer architecture for autonomous CLI discovery and installation. It automatically finds, caches, and installs CLIs across package managers. - Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything) - Tags: architecture - Published: 2026-05-18 --- **CLI-Hub employs a modular three-layer architecture—encompassing the Registry, Installer, and CLI Front-end—to automatically discover, cache, and install command-line tools across multiple package managers using a strategy-pattern dispatcher.** The CLI-Hub module within the HKUDS/CLI-Anything repository provides the autonomous backbone for discovering and installing command-line interfaces without manual configuration. By separating concerns into distinct architectural layers, CLI-Hub enables users to search a unified registry and install tools via pip, npm, uv, or generic commands through a single intuitive interface. ## The Three-Layer Architecture of CLI-Hub CLI-Hub is structured into three cooperating layers that handle distinct responsibilities: data discovery, installation execution, and user interaction. ### Registry Layer ([`cli_hub/registry.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/registry.py)) The Registry layer manages all remote data operations and local caching. It downloads JSON manifests from `REGISTRY_URL` and `PUBLIC_REGISTRY_URL`, then stores them in `$HOME/.cli-hub/registry_cache.json` (and [`public_registry_cache.json`](https://github.com/HKUDS/CLI-Anything/blob/main/public_registry_cache.json) respectively). The `_fetch_json()` function (lines 32-57) handles the actual HTTP retrieval and writes the payload with a timestamp. If the cached file is younger than `CACHE_TTL` (1 hour), the system returns cached data immediately. The `fetch_all_clis()` function (lines 73-90) merges harness and public registry entries, tagging each record with `_source` metadata. Lookup utilities like `get_cli(name)`, `search_clis(query)`, and `list_categories()` operate on this unified, read-only cache, enabling case-insensitive name resolution and full-text search across `name`, `description`, `category`, and `display_name` fields. ### Installer Layer ([`cli_hub/installer.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/installer.py)) The Installer implements a strategy pattern to handle diverse package managers. The `_install_strategy(cli)` function (lines 88-101) determines the appropriate backend by first checking for an explicit `install_strategy` field, then falling back to heuristics: harness entries default to `pip`, presence of `npm_package` triggers `npm`, and the `package_manager` field selects `uv`, `bundled`, or generic `command`. The `_perform_action(cli, action)` dispatcher (lines 84-94) routes to specific handlers: `_pip_install`, `_npm_uninstall`, `_uv_update`, etc. Each handler constructs the appropriate system command, while `_run_command()` (lines 52-66) executes it—using `subprocess.run` with `shell=True` for complex commands or a plain argument list otherwise. Upon success, `install_cli()` (lines 21-35) records the installation in `$HOME/.cli-hub/installed.json` via `_installed_entry()`, maintaining a local state of managed tools. ### CLI Front-end Layer ([`cli_hub/cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/cli.py)) The user-facing interface is built on **Click** and exposed through [`cli_hub/cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/cli.py). The `main()` entry point (lines 50-62) initializes analytics and dispatches to sub-commands including `install`, `uninstall`, `list`, `search`, `info`, `update`, and `launch`. Commands like `install ` invoke `install_cli(name)` from the Installer layer, while `search` delegates to `search_clis()` in the Registry layer. The front-end handles display formatting—such as `_source_tag()` for colored public/harness labels—and ensures consistent error handling and analytics tracking (`track_install`, etc.) across all operations. ## Step-by-Step Discovery and Installation Flow Understanding the end-to-end flow reveals how the three layers cooperate to achieve autonomous CLI management. ### Registry Fetching and Merging When a user runs a search or install command, the system first ensures registry data is available. `fetch_registry()` and `fetch_public_registry()` retrieve the latest JSON if the cache is stale or missing. The merge operation in `fetch_all_clis()` produces a single list where each entry retains its source provenance, allowing the system to prioritize or filter based on origin. ### Strategy Detection and Execution For installation requests, `_install_strategy()` analyzes the CLI metadata to select the appropriate handler. The strategy map in `_perform_action()` then executes the corresponding install, uninstall, or update logic. For example, a pip-based CLI triggers `_pip_install`, which constructs `python -m pip install ` commands, while an npm-based tool routes through `_npm_install`. ### Local State Management Every successful mutation updates `$HOME/.cli-hub/installed.json`. This bookkeeping file tracks which CLIs are managed by CLI-Hub, their installation strategies, and metadata required for updates or removal. The design ensures that uninstall and update operations know exactly which strategy to reverse or refresh, even if the upstream registry changes. ## Practical Example: From Search to Launch The following interaction demonstrates the autonomous flow from discovery to execution: ```bash $ cli-hub search video # Queries merged registry cache $ cli-hub install videocode # Resolves metadata, selects pip strategy $ cli-hub launch videocode --input my_video.mp4 # Executes installed binary ``` In step one, `search_clis("video")` filters the cached registry without network calls. Step two invokes `install_cli("videocode")`, which calls `_install_strategy()` to choose `_pip_install`, executes the command via `_run_command()`, and records the result to [`installed.json`](https://github.com/HKUDS/CLI-Anything/blob/main/installed.json). Step three verifies the binary exists on `$PATH` and launches it. ## Summary - **Three-layer separation** isolates registry management ([`registry.py`](https://github.com/HKUDS/CLI-Anything/blob/main/registry.py)), installation logic ([`installer.py`](https://github.com/HKUDS/CLI-Anything/blob/main/installer.py)), and user interface ([`cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli.py)) for maintainability. - **TTL-based caching** stores registry data in `$HOME/.cli-hub/` with a one-hour expiration, enabling fast offline lookups after the initial fetch. - **Strategy-pattern installer** supports pip, npm, uv, generic shell commands, and bundled binaries through pluggable handlers in `_perform_action()`. - **Local state tracking** maintains an inventory of installed tools in [`installed.json`](https://github.com/HKUDS/CLI-Anything/blob/main/installed.json), ensuring reliable update and uninstall operations. - **Click-based CLI** provides a consistent command structure that delegates to underlying layers without embedding business logic. ## Frequently Asked Questions ### How does CLI-Hub determine which installation strategy to use? The `_install_strategy()` function in [`cli_hub/installer.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/installer.py) (lines 88-101) implements a cascading decision tree. It first checks the CLI record for an explicit `install_strategy` field. If absent, it applies heuristics: harness entries default to `pip`, presence of `npm_package` or `package_manager=="npm"` selects `npm`, `package_manager=="uv"` selects `uv`, and `package_manager=="bundled"` marks the tool as pre-installed. All other cases fall back to the generic `command` strategy. ### Where does CLI-Hub store registry data and installation records? CLI-Hub maintains two local JSON files in `$HOME/.cli-hub/`: [`registry_cache.json`](https://github.com/HKUDS/CLI-Anything/blob/main/registry_cache.json) (and [`public_registry_cache.json`](https://github.com/HKUDS/CLI-Anything/blob/main/public_registry_cache.json)) store downloaded manifests with timestamps for TTL validation, while [`installed.json`](https://github.com/HKUDS/CLI-Anything/blob/main/installed.json) tracks the user's installed CLIs via the `_installed_entry()` helper. These files are created on-demand, allowing the tool to function in read-only environments until a write is required. ### Can CLI-Hub operate without an internet connection? Yes, for discovery and listing operations. Because the Registry layer caches merged manifests locally, functions like `search_clis()`, `get_cli()`, and `list_categories()` operate entirely on local data after the initial fetch. However, actual installation, update, and uninstall operations require network connectivity to reach their respective package managers (PyPI, npm registry, etc.). ### What makes the CLI-Hub architecture extensible to new package managers? The strategy pattern in [`cli_hub/installer.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli_hub/installer.py) decouples the package manager interface from the CLI front-end. Adding support for a new system (e.g., Homebrew or Cargo) requires only three steps: implement new handler functions (e.g., `_brew_install`), add detection logic to `_install_strategy()`, and register the handlers in the `_perform_action()` map. The Click-based interface in [`cli.py`](https://github.com/HKUDS/CLI-Anything/blob/main/cli.py) remains unchanged, as it delegates all installation concerns to the Installer layer.