cmdhub-command-discovery

name	cmdhub-command-discovery
description	Discover the right command-line tool or subcommand for a task, offline and instantly, via `cmdh`. Use whenever you need to find which CLI command does something ("how do I create a VPC on AWS", "delete files", "convert image to webp"), get its install method for the current OS, or check a command's risk level before running it. Backed by a local hybrid (FTS + vector) search over a registry of 100k+ tools and subcommands — no network, sub-millisecond.
license	MIT

CmdHub Command Discovery

cmdh turns a natural-language intent into concrete CLI commands with their install instructions, risk level, and usage template. It searches a local, signed offline database (SQLite FTS5 + ONNX vector search, RRF fusion).

When to use this skill

• You need the command/subcommand for a task but don't remember the exact name (e.g. "list ec2 instances" → aws ec2 describe-instances).
• You need the correct install command for the user's OS (Arch→yay/pacman, Debian/Fedora→apt/dnf or cargo/pip/npm, macOS→brew, Windows→scoop).
• You must check a command's risk level (safe/medium/dangerous) before executing — never auto-run a dangerous command without confirmation.
• You want offline, zero-token discovery instead of guessing.

How to use

Search (JSON to stdout; logs to stderr):

cmdh search "I want to create a vpc on aws" --limit 5

Each result is an ACI contract:

{
  "app_id": "org.cmdhub.aws-cli",
  "name": "aws",
  "cmd_path": "aws.ec2.create-vpc",
  "node_type": "sub",
  "description": "Creates a VPC with the specified CIDR blocks.",
  "risk_level": "dangerous",
  "install_command": "sudo pacman -S aws-cli-v2",
  "example_template": "aws ec2 create-vpc --cidr-block {{cidr}}",
  "status": "installed"
}

Guidance for agents:

• Prefer the result whose cmd_path and description best match the intent; raise --limit to see more candidates. Phrase queries with the resource/verb ("create vpc", "list instances") for the sharpest results.
• If status is not_installed, surface install_command (already resolved for the host OS) before running.
• Respect risk_level: confirm with the user before any dangerous command.
• Use --full / --usage / --minimal to control output verbosity.

Search tips (get the right command faster)

The index searches across name, cmd_path, description, and curated topics (keyword tags like azure, networking, vcs) with hybrid keyword + vector ranking.

• Name the tool when you know it — "create a vpc on aws", "github auth login". This scopes results to that tool and surfaces the exact subcommand.
• Use the resource + action — "create vpc", "list instances", "delete bucket". Concrete nouns/verbs match real command names far better than vague phrases.
• Brand/concept words work — "azure", "kubernetes", "container registry" hit the right tool via topic tags, even when the binary name differs (az, kubectl).
• Raise --limit (default 5) to see more candidates when the top hit isn't ideal; results are diversified so one tool can't flood the list.
• Check risk_level before executing; confirm anything dangerous.
• If a query returns nothing useful, re-phrase with the concrete tool/resource term rather than an abstract sentence.

MCP integration

For tool-calling agents, run the MCP server (cmdhub-mcp, stdio JSON-RPC) which exposes two tools:

• cmdhub_search — { "query": string, "limit"?: number } → ranked ACI results.
• cmdhub_execute — { "cmd_path": string, "args"?: [string] } → runs the tool (refuses dangerous commands unless explicitly allowed).

Register it in your MCP client config; no API key or network required.

Keeping data fresh

cmdh sync pulls the latest signed cmdhub.db.zst from the CDN (Ed25519-verified, atomic swap). The database is continuously updated from package registries (crates.io, AUR, PyPI, npm, Homebrew) and deep --help probes.