CLI-Anything

Before running pip install from a URL the user provides (not the CLI-Anything hub), confirm with the user: "This will install a Python package from [URL]. Proceed?" Do not auto-install from untrusted sources. The pre-built CLIs from github.com/HKUDS/CLI-Anything are trusted and can be installed without confirmation.

Modes of Operation

Mode selection: When the user requests a CLI for specific software:

1. First check if it's in the pre-built catalog (Mode 1). If available, offer to install it.
2. If not in the catalog, ask the user for a source path or GitHub URL before starting the build pipeline (Mode 2). Do not attempt to build without source material.
3. If the user already has a harness installed, use Mode 3 (refine) or Mode 4 (use) based on whether they want to add features or perform a task.

1. Discover & Install Pre-Built CLIs

Pre-built CLIs are available in the hub. Always check the live catalog first — it's auto-updated and may have CLIs not listed below:

# Fetch the live catalog to see what's available
curl -s https://hkuds.github.io/CLI-Anything/SKILL.txt | head -100

# Install a specific CLI
pip install "git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=<software>/agent-harness"

# Example: install GIMP CLI
pip install "git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=gimp/agent-harness"

# Verify
cli-anything-gimp --help

Available CLIs by category:

2. Build a New CLI Harness

When the user wants to create a CLI for software not in the hub:

Input: A local source path (./gimp) or GitHub URL pointing to the software's source code or documentation.

Before starting: Verify the path/URL exists and is accessible. Check the hub catalog to see if a CLI already exists — if so, ask the user whether to install the existing one or build a custom harness.

7-Phase Pipeline:

1. Analyze — Identify backend engine, map GUI actions to API calls, catalog data model
2. Design — Define command groups, state model, output format (human + JSON)
3. Implement — Build Click CLI with subcommands + REPL, --json flag, session state
4. Plan tests — Write TEST.md before any test code
5. Write tests — Unit tests (test_core.py) + E2E tests (test_full_e2e.py) with real backends
6. Document — README, usage examples, agent-discoverable SKILL.md
7. Package — setup.py with namespace packages, console_scripts entry point

Decision gates:

• After Analyze: if the software has no scriptable backend (no CLI, no Python API, no headless mode), stop and report to the user — not all software is CLI-Anything compatible.
• After Implement: verify the CLI installs and --help works before proceeding.
• After Write tests: run them. If the backend software isn't installed locally, note which tests are expected to fail and why.

If any phase fails, diagnose the issue and retry that phase before proceeding.

Output structure:

<software>/
└── agent-harness/
    ├── <SOFTWARE>.md          # Architecture doc
    ├── setup.py               # pip-installable
    └── cli_anything/
        └── <software>/
            ├── README.md
            ├── __init__.py
            ├── __main__.py
            ├── <software>_cli.py   # Main CLI (Click)
            ├── core/               # Business logic
            ├── utils/
            │   ├── repl_skin.py    # REPL interface (copy from plugin)
            │   └── <software>_backend.py  # Real software wrapper
            ├── skills/
            │   └── SKILL.md        # AI-discoverable skill
            └── tests/
                ├── TEST.md         # Test plan
                ├── test_core.py    # Unit tests
                └── test_full_e2e.py  # E2E tests

3. Refine an Existing Harness

When the harness already exists:

1. Inventory current commands and tests
2. Gap analysis against target software capabilities
3. Prioritize: high-impact missing features, easy backend wrappers, composable additions
4. Implement additions without removing existing commands (unless explicitly asked)
5. Run tests to verify nothing breaks

4. Use an Installed CLI

All CLI-Anything CLIs follow the same patterns:

# One-shot subcommand mode
cli-anything-<software> --json <command> [options]

# Interactive REPL mode (default when no subcommand)
cli-anything-<software>
> help
> project new -o myproject.json
> undo
> exit

# Common patterns
cli-anything-<software> --help          # See all commands
cli-anything-<software> --json status   # Machine-readable status

Key features of every CLI:

• --json flag for machine-readable output
• REPL mode with history, tab-completion, undo/redo (up to 50 levels)
• Session state persistence via JSON project files
• Real software backend integration (not mock implementations)

Implementation Rules

Backend Integration

Prefer the real software backend over reimplementation — re-implementing software logic is error-prone and produces a CLI that diverges from the real tool's behavior. Create utils/<software>_backend.py that wraps the actual executable:

import shutil, subprocess

def find_software():
    path = shutil.which("software-name")
    if not path:
        raise RuntimeError("software-name not found. Install: brew install software-name")
    return path

def render(project_path, output_path):
    exe = find_software()
    subprocess.run([exe, "--headless", project_path, "-o", output_path], check=True)

Packaging

• Use find_namespace_packages(include=["cli_anything.*"])
• Keep cli_anything/ as a namespace package (no top-level __init__.py)
• Entry point: cli-anything-<software>=cli_anything.<software>.<software>_cli:main

REPL Skin

Copy repl_skin.py from the CLI-Anything repository (cli-anything-plugin/repl_skin.py) into utils/. It provides:

• Branded startup banner (auto-detects SKILL.md path)
• Styled prompt with project name and modified indicator
• help(), success(), error(), warning(), info(), status(), table(), progress()
• print_goodbye() for clean exit

Testing

• Create a TEST.md plan before writing test code — this prevents test scope from drifting and documents what the tests should cover
• Unit tests in test_core.py — test core functions in isolation
• E2E tests in test_full_e2e.py — invoke real software, verify output files
• CLI subprocess tests — test installed command via subprocess.run()
• Tests should fail (not skip) when backend software is missing — skipping hides real integration problems and gives false confidence
• Verify outputs programmatically (magic bytes, ZIP structure, pixel analysis)

Example Workflows

Install and Use GIMP CLI

pip install "git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=gimp/agent-harness"

cli-anything-gimp --json project new -o scene.json
cli-anything-gimp --project scene.json layer add-from-file photo.jpg
cli-anything-gimp --project scene.json filter add blur --layer 0 --params "radius=5"
cli-anything-gimp --project scene.json export render output.png --overwrite

Install and Use Blender CLI

pip install "git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=blender/agent-harness"

cli-anything-blender --json scene new -o scene.json
cli-anything-blender --project scene.json object add cube --name "Box"
cli-anything-blender --project scene.json material create --name "Red" --color 1,0,0,1
cli-anything-blender --project scene.json render execute output.png --overwrite

Build a CLI for New Software

# Clone or point to software source
git clone https://github.com/example/my-software.git

# Use CLI-Anything methodology to build harness
# (Follow the 7-phase pipeline above)
cd my-software/agent-harness
pip install -e .
cli-anything-my-software --help

Troubleshooting