ai, agents, deep dive,

Deep Dive: How CLI-Anything Turns GUI Software Into Agent Tools

Cui Cui Follow Nov 20, 2026 · 5 mins read
Deep Dive: How CLI-Anything Turns GUI Software Into Agent Tools
Share this

Companion to the hands-on tutorial: Make any software agent-native with CLI-Anything on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.

HKUDS/CLI-Anything (about 60.7k stars per the GitHub API on 2026-11-20, Apache 2.0) describes itself as “Making ALL Software Agent-Native”. I cloned it and read cli-hub/cli_hub/registry.py, cli-hub/cli_hub/installer.py, cli-hub/cli_hub/cli.py, cli-anything-plugin/HARNESS.md, cli-anything-plugin/commands/cli-anything.md and cli-hub-meta-skill/SKILL.md. The repo also holds many per-application harness directories (gimp, blender, drawio and more).

The workflow in motion

Animated workflow of CLI-Hub: an agent searches, cli-hub reads the cached registries, the entry picks an install strategy, the installer puts a CLI on PATH, the CLI drives the real software, and a JSON result returns to the agent

Architecture

There are two separate systems. The first is the consumer side: cli-hub, a Click app. Its commands (install, uninstall, update, list, search, info, launch, plus previews and matrix groups) name-based ones (install, update, info, launch) resolve through the registry, while list and search read the catalog and previews works on preview and session references. The second is the producer side: a plugin whose /cli-anything command tells a coding agent to follow HARNESS.md and generate a harness.

The registry has two sources, tagged as harness and public, and the installer chooses how to install per entry.

The producer side is a pipeline: HARNESS.md defines Phases 1 to 7 (analysis, architecture design, implementation, test planning, test implementation, test documentation, PyPI publishing) plus a Phase 6.5 that generates a SKILL.md.

The core design idea

The key idea is that the CLI is a thin, honest wrapper around the real application, and the methodology is written down for an agent to follow. HARNESS.md states it as a rule: the real software is a hard dependency, the CLI must invoke it for rendering and export, and it should not “gracefully degrade to a fallback library”. If the software is missing, the CLI errors with install instructions. That keeps agent output trustworthy: a rendered PDF came from LibreOffice, not from an approximation.

The other half is a contract an agent can rely on. Every command must support --json, errors must be loud and clear so agents can self-correct, and introspection commands (info, list, status) let an agent look before it mutates. Tests must go beyond “it ran”: exports are verified by analyzing the output.

Because generation is a prompt-driven procedure rather than a code generator, the repo ships the SOP as a document. The command file opens with:

<!-- cli-anything-plugin/commands/cli-anything.md -->
**Before doing anything else, you MUST read `./HARNESS.md`.**
... Do not improvise — follow the harness specification.

On the hub side, the registry code is deliberately resilient. It fetches JSON, caches it for an hour, and falls back to a stale cache if the network fails:

# cli-hub/cli_hub/registry.py
CACHE_TTL = 3600  # 1 hour
...
except (requests.RequestException, ValueError):
    cached_data = _load_cached_data(cache_file)
    if cached_data is not None:
        return cached_data
    raise

The public registry is optional: fetch_public_registry swallows any exception and returns None, so a failure there never blocks harness CLIs.

The installer picks a strategy per entry. An explicit install_strategy field wins; otherwise harness entries default to pip (excerpt after that override check):

# cli-hub/cli_hub/installer.py
if cli.get("_source", "harness") == "harness":
    return "pip"
if cli.get("npm_package") or cli.get("package_manager") == "npm":
    return "npm"

Install commands from the registry may contain shell operators such as curl ... | bash. The code runs them through a shell only when it detects metacharacters, and its docstring states the commands “come from the trusted registry, not from user input”. That is a real trust boundary worth knowing about: the registry is the thing you are trusting.

Finally, launch replaces the hub process with the CLI, so there is no wrapper in the way:

# cli-hub/cli_hub/cli.py
os.execvp(entry, [entry] + list(args))

It first checks shutil.which(entry) and tells you to run cli-hub install <name> if the entry point is not on PATH.

Takeaways

  • Agent-native does not mean new protocol: a well-behaved CLI with --json, introspection and clear errors is enough.
  • Keep the real application in the loop; never fake the renderer.
  • Ship the methodology as a document the agent must read first, and add a SKILL.md so the result is discoverable.
  • A registry is a trust boundary: review entries before installing, especially ones with shell install commands.
  • Cache with a stale fallback; agents should not fail because a catalog fetch blipped.

Work with me

Want your own internal tool made agent-ready? Get in touch.

Join Newsletter
Get the latest news right in your inbox. We never spam!
Cui
Written by Cui Follow
Hi, I am Z, the coder for cuizhanming.com!

Click to load Disqus comments