Frequently Asked Questions

CliHub is an open-source CLI tool marketplace designed for AI agents. It provides a curated registry of 104 command-line tools that AI agents can discover, install, and use. Unlike MCP which injects tool schemas into every prompt, CliHub's CLI-based approach costs zero tokens until the agent actually needs a tool. Install with pip install clihub-ai.

Run pip install clihub-ai or pipx install clihub-ai for an isolated environment. Requires Python 3.10+. After installation, run clihub doctor to verify your system is ready and see which package managers are available.

Yes. CliHub is completely free and open source under the MIT license. The source code is available at github.com/clihub-ai/clihub. The registry of 104 tools is bundled with the package — no account or API key required.

CliHub works on macOS, Linux, and Windows. It requires Python 3.10 or newer. The tools it installs use various package managers (brew, pip, npm, cargo), so availability depends on your system.

Yes. The full tool registry is bundled with CliHub — search, list, and info commands work completely offline. Only the install command requires internet access to download tools from package managers.

AI agents use CliHub through two steps. First, run clihub list --json to get the full tool catalog with descriptions and agent hints. The agent reads this catalog, picks the right tool for the task, and runs clihub install <tool> to install it. Then the agent uses the tool directly. Every CliHub command supports --json for structured output.

Every CliHub command supports --json for structured, machine-readable output. For example, clihub list --json returns a JSON array of all 104 tools with name, description, categories, install method, and agent_hints. clihub install jq --json returns: Exit code 0 means success, 1 means error, 2 means not found.

CLI tools cost zero tokens in the agent's context window until actually used. MCP servers inject 8,000-15,000 tokens of JSON schemas into every prompt, even when unused. LLMs are already trained on billions of shell examples — they know how to use git, curl, jq, and grep without any schema. CLI tools also compose naturally with Unix pipes.

Each tool in the CliHub registry includes agent_hints — metadata that tells AI agents when and how to use the tool. This includes when_to_use (a natural language description like "Parse, filter, or transform JSON data") and example_usage (2-3 real command examples). These hints help agents pick the right tool without needing to run --help first.

CliHub uses standard Unix exit codes. Exit code 0 means success. Exit code 1 means an error occurred (e.g., installation failed). Exit code 2 means not found (e.g., no search results, tool not in registry). Errors are written to stderr, so agents can reliably detect and handle failures.

CliHub currently has 104 curated CLI tools across 17 categories including data processing (jq, yq, csvkit), search (ripgrep, fd, fzf), networking (curl, httpie, wget), development (gh, lazygit, ruff), media (ffmpeg, imagemagick), and more. Every tool is verified and includes agent-readable hints.

Run clihub convert <tool> to auto-detect metadata from any binary on your PATH, then edit the generated clihub.yaml to add categories, tags, and agent_hints. Run clihub submit clihub.yaml to validate the manifest. Finally, open a pull request to the GitHub repository. You can also edit src/clihub/data/registry.json directly.

CliHub supports four package managers: brew (Homebrew), pip (Python), npm (Node.js), and cargo (Rust). When you run clihub install <tool>, it auto-detects the best package manager based on the tool's registry entry. Use --via <method> to force a specific package manager.

An agent-ready CLI tool has three properties. First, it self-documents via --help so agents can learn its interface. Second, it uses standard exit codes (0 for success, non-zero for errors) so agents can detect failures. Third, it produces structured output (ideally with a --json flag) so agents can parse results programmatically.

CliHub and MCP solve the same problem — giving AI agents access to tools — but with fundamentally different approaches. MCP uses JSON-RPC and injects full tool schemas (8,000-15,000 tokens) into every prompt. CliHub uses CLI tools that cost zero tokens until used. MCP requires building and maintaining servers. CliHub tools already exist on your PATH. See our detailed comparison.

Yes. CliHub and MCP are not mutually exclusive. You might use MCP for stateful services that need persistent connections (like databases or authenticated APIs) while using CliHub for everything else (file processing, data transformation, code formatting, etc.). This hybrid approach minimizes context window overhead while keeping MCP for what it does best.

Function calling (tool_use) requires defining schemas for every tool upfront and injecting them into the prompt — similar to MCP's token cost problem. CLI tools are already self-documenting via --help and already exist as battle-tested binaries. An agent using CliHub doesn't need predefined schemas — it discovers tools at runtime and uses them like a developer would.