Documentation

Drive any app from the command line

CLI-Hub is a registry and installer for agent-native CLIs. Install a tool by name, launch it, and — when a task spans several tools — pull in a capability-based Workflow Matrix. Every command is built for both humans and AI agents, with --json output and a documented exit-code contract.

Getting started

Install

CLI-Hub ships as the cli-anything-hub package and installs the cli-hub command. It needs Python 3.10 or newer.

$ pip install cli-anything-hub
$ cli-hub --version

That single command is the entry point for everything below — browsing the catalog, installing tools, and working with matrices. From here you can also hand an agent the meta-skill SKILL.md so it can discover and install CLIs autonomously.

Two-minute tour

Quick start

Find a tool, install it, and run it — or scope a whole workflow to just what your task needs.

# Browse and install a single CLI
$ cli-hub search diagram
$ cli-hub install drawio
$ cli-hub launch drawio --help

# Ask what's needed for a task across every matrix
$ cli-hub can "transcribe audio"

# Check a matrix, then install only the capability you need
$ cli-hub matrix preflight video-creation --summary
$ cli-hub matrix install video-creation --capability text.transcribe

Tip. Add --json to almost any command for machine-readable output, and chain on exit codes (see Exit codes) to make scripts and agents react without parsing text.

The catalog

Catalog commands

The catalog is the flat list of individual CLIs — first-party harness tools published by CLI-Anything and curated public tools. These commands discover, install, and run them.

cli-hub list
List every available CLI, grouped by category, with an installed marker.
-c, --category <name>Filter to one category.
-s, --source <harness|public|npm|all>Filter by source (npm is an alias for public).
--jsonMachine-readable output.
cli-hub search <query>
Search CLIs by name, description, or category.
--jsonMachine-readable output.
cli-hub info <name>
Show full detail for one CLI — description, category, source, version, requirements, entry point, homepage, and contributors.
cli-hub install <name>
Install a CLI from the registry. Harness tools install via pip; public tools use their declared strategy (npm / uv / command).
cli-hub launch <name> [args…]
Launch an installed CLI, passing every argument after the name straight through to it.
cli-hub update <name>  ·  cli-hub uninstall <name>
Update an installed CLI to the latest version, or remove it.
cli-hub previews <inspect|html|watch|open>
Inspect, render, watch, or open preview bundles and live sessions produced by harness CLIs (e.g. FreeCAD / Blender preview loops). watch and open serve a live, auto-refreshing page.
Concepts

Workflow matrices

A real task — “make a captioned video” — rarely maps to one tool. A matrix bundles a domain into capabilities (the verbs an agent calls) and, for each, several providers (concrete ways to fulfil it). You pick a path by capability, not by memorising which of fourteen packages to install.

Matrix  ── a capability bundle for one domain (e.g. video-creation)
│
├─ capabilities[]   verbs an agent can call — visual.generate, text.transcribe …
│   └─ providers[]   concrete ways to fulfil a capability, each tagged with a kind
│
├─ recipes[]        named subsets of capabilities for a specific task
├─ clis[]           the flat list that matrix install actually installs
└─ SKILL.md         the provider-selection handbook, rendered locally on install

Provider kinds

Every provider declares a kind that tells you how it’s obtained and what it costs:

harness-cli

A first-party CLI you can install with cli-hub; each ships its own SKILL.md.

public-cli

A third-party CLI installed via brew / npm / pip.

python

A Python library used directly (a free fallback).

native

A native binary on the system, such as ffmpeg.

api

A cloud API — needs a key and explicit user consent.

agent-skill

An external agent skill the agent installs itself; not counted by preflight.

Preflight reports, it doesn’t choose. Registry order is documentation order, not a ranking. preflight tells you what’s available; the agent picks the provider using the rules in the matrix’s SKILL.md. Paid APIs are never used without configured keys and user consent.

The matrix command family

Matrix commands

All matrix operations live under cli-hub matrix, plus the top-level cli-hub can shortcut for capability search. Every subcommand supports --json.

Discover

cli-hub can <query>
Search capabilities across all matrices for a task, with per-provider availability on this machine. Exit 0 if there are hits, 1 if none.
--jsonEmit capability matches as JSON.
$ cli-hub can "download bilibili video"
  video.download  (video-creation)
    available here: yt-dlp · missing: BBDown, lux
    next: cli-hub matrix preflight video-creation -c video.download
cli-hub matrix list
List all matrices with their description and how many member CLIs are installed.
--jsonMachine-readable output.
cli-hub matrix search <query>
Search matrices by name, capability, provider, recipe, or gap — with match attribution (which capability matched, and on which field).
--jsonIncludes matched_capabilities[].
cli-hub matrix info <name>
Full detail for one matrix — members and status, capabilities with provider counts, recipes, and known gaps.
--jsonMachine-readable output.
cli-hub matrix recipes
List task-oriented recipes across every matrix, each with its capabilities and a ready-to-run preflight command.
--search <text>Filter by id, description, or capability.
--jsonMachine-readable output.

Preflight

Preflight is the pivot of the whole flow: it reports which providers are actually usable in your current environment, so you (or an agent) decide what to install before touching anything.

cli-hub matrix preflight <name>
Check provider availability per capability. Exits 0 when every (filtered) capability has at least one usable provider, 3 when there’s a gap.
-c, --capability <id>Check just one capability.
--recipe <id>Check only the capabilities a recipe uses.
--offlineConsider only offline-capable providers.
--fix-hintsPrint an install command under each missing provider.
--summaryPrint only the two-line summary.
--jsonMachine-readable output.
# Gate an action on coverage — only proceed if the recipe is fully satisfiable
$ cli-hub matrix preflight video-creation --recipe screencast-tutorial --json \
    || echo "capability gap — read the missing list before installing"

Install

cli-hub matrix install <name>
Install a matrix’s CLIs. With no scope flag it installs every member CLI; the scope flags below install just a subset. Installation is idempotent — already-installed tools are skipped.
--dry-runShow the install plan with zero side effects.
-c, --capability <id>Install only the CLIs behind one capability.
--recipe <id>Install only the CLIs a recipe uses.
--only <a,b,c>Install a named comma-separated subset of the matrix’s CLIs.
--resumeRetry only the CLIs that failed last time.
--skill-onlyRender the matrix skill (SKILL.md + references + scripts) without installing CLIs.
--jsonMachine-readable plan or result.
$ cli-hub matrix install video-creation --dry-run
  Plan: video-creation
  skip (already installed): audacity, gimp, kdenlive
  install via pip:          inkscape, krita, obs-studio, …
  not managed here:         python libs, native binaries, cloud APIs — see preflight

The scope flags (--capability, --recipe, --only) are mutually exclusive. Per-matrix install state is recorded under ~/.cli-hub/matrix_state.json, which is what powers --resume.

Repair

cli-hub matrix doctor <name>
Audit install completeness for a matrix’s CLIs — flags anything recorded as installed but missing from PATH, and suggests a fix. (Preflight asks “is a provider usable?”; doctor asks “is what I installed still healthy?”)
--jsonMachine-readable audit.
Contract

Exit codes

The matrix command family follows one exit-code contract, so scripts and agents can branch without reading text. Catalog commands use the simpler 0 / 1 success-or-failure convention.

0
Success
All checks passed, or every capability gap is covered.
1
Failure
Matrix or capability not found; nothing could be installed.
2
Usage error
Mutually exclusive flags, or an invalid capability / recipe / --only name.
3
Partial
A capability gap, or some CLIs installed while others failed or are broken.
For agents & scripts

JSON & automation

CLI-Hub is built to be driven by AI agents as much as by people. Two design choices make that reliable:

  • Structured output everywhere. Catalog commands and the whole matrix family accept --json — including matrix install, whose JSON carries the full plan or result. No screen-scraping required.
  • Exit codes as control flow. Combine the contract above with && / || to gate steps — e.g. preflight a recipe, and only install when it returns 0.

After installing a matrix, its SKILL.md is rendered to your machine. Read it: it contains the provider-selection rules, the suggest-to-user template for paid upgrades, and references — the judgement an agent needs that the registry alone doesn’t encode.

The meta-skill SKILL.md includes a Workflow Matrices section, and the site publishes llms.txt plus the machine-readable registries — give an agent those entry points and it can go from cold start to “preflight → install by capability → JSON result” on its own.

Reference

Registries & config

CLI-Hub reads three published registries and caches them locally (one-hour TTL) under ~/.cli-hub/:

  • registry.json — first-party harness CLIs.
  • public_registry.json — curated public CLIs.
  • matrix_registry.json — matrices: capabilities × providers, with preflight contracts.

They’re served from the project’s GitHub Pages domain (for example …/CLI-Anything/matrix_registry.json). Local state lives alongside the cache: installed.json tracks installed CLIs, and matrix_state.json records per-matrix install outcomes for --resume.

Environment

  • CLI_HUB_NO_ANALYTICS=1 — opt out of anonymous, fire-and-forget usage analytics.
  • CLI-Hub auto-detects when it’s invoked by an AI agent (Claude Code, Codex, Cursor, and others) for analytics bucketing only.
  • Color is suppressed automatically when output is piped or not a TTY, keeping logs and parsers clean.

Analytics never block your workflow and can be turned off entirely. Matrices are the differentiator here — start from the Matrices section or run cli-hub matrix list to see what’s available.