GUI를 클릭하지 말고 CLI로 부르게 하라: HKUDS/CLI-Anything v0.4.0의 7단계 하네스 생성·HARNESS.md 원칙·CLI-Hub 신뢰 경계 심층 해부

AI 에이전트에게 GIMP나 LibreOffice, Blender 같은 데스크톱 소프트웨어를 맡기는 방법은 크게 두 갈래였다. 화면을 캡처해 좌표를 클릭하는 GUI 에이전트(컴퓨터 유즈), 아니면 앱마다 API나 MCP 서버를 따로 만드는 방식이다. 오늘(2026-10-18) GitHub Trending 전체 일간 4위·Python 일간 3위에 오른 HKUDS/CLI-Anything은 세 번째 길을 고집한다. 소프트웨어의 소스 코드를 에이전트가 읽게 해서, 그 앱 전용의 상태 있는 CLI(“하네스”)를 자동으로 만들게 한다. 결과물은 cli-anything-<앱> --json … 형태의 평범한 파이썬 명령이고, 실제 렌더링은 끝까지 원래 소프트웨어(예: soffice --headless)가 맡는다.

이 글은 “아무 앱이나 에이전트가 쓰게 해 준다”는 홍보 문구를 그대로 옮기지 않는다. 대신 ① 7단계 생성 파이프라인과 747줄짜리 지침서 HARNESS.md가 실제로 무엇을 강제하는지, ② 이미 만들어진 하네스 하나(LibreOffice)가 내부에서 어떻게 생겼는지, ③ 패키지 매니저 cli-hub의 레지스트리·설치·분석(telemetry) 경로에 어떤 신뢰 가정이 숨어 있는지를 코드와 박스 스모크 테스트로 확인한다. 수치는 모두 2026-10-18 16:50~17:00 KST에 main HEAD 34f5195를 직접 체크아웃해 집계·실행한 값이다.

한눈에 보기: 오늘 체크아웃 기준

왜 지금 다시 트렌딩인가

CLI-Anything은 3월에 공개돼 이미 5만 스타를 넘긴 저장소라 “신작”은 아니다. 그럼에도 오늘 다시 일간 상위권에 오른 데는 몇 가지 신호가 겹친다. 같은 날 Trending 1위가 Anthropic의 공식 Claude Code 플러그인 디렉터리이고, 상위권 대부분이 에이전트 스킬·하네스류다. 즉 “에이전트에게 무엇을 쥐여 줄 것인가”가 이번 주 개발자들의 공통 관심사이고, CLI-Anything은 그 질문에 “앱 전체를 CLI로”라는 가장 큰 단위의 답을 내놓는 프로젝트다.

문제 정의: 에이전트가 소프트웨어를 다루는 세 가지 방법

핵심 주장은 간단하다. LLM은 텍스트 명령을 읽고 쓰는 데 가장 능숙하고, CLI는 --help로 스스로를 설명하며 파이프로 조합된다. 그렇다면 “GUI를 흉내 내는 에이전트”보다 “에이전트가 쓰기 좋은 CLI를 만드는 에이전트”가 장기적으로 싸고 안정적이라는 것이다. 이 글의 이전 심층 분석에서 다룬 GUI 에이전트 인프라(trycua/cua)와는 정반대 방향의 베팅이다.

저장소 구조: 생성기 · 하네스 모노레포 · 패키지 매니저

7단계 생성 파이프라인: /cli-anything 한 번에 일어나는 일

생성기의 실체는 코드라기보다 에이전트에게 주는 절차서다. commands/cli-anything.md는 첫 줄부터 “무엇보다 먼저 HARNESS.md를 읽어라, 즉흥적으로 하지 마라”고 못 박는다. 인자로는 반드시 소스 경로나 저장소 URL을 받아야 하며, “gimp” 같은 이름만으로는 거부한다. 소스 분석이 파이프라인의 출발점이기 때문이다.

초기 생성 뒤에는 /cli-anything:refine <경로> "초점"으로 앱 전체 기능과 현재 CLI의 차이를 분석해 명령·테스트·문서를 덧붙이고, :test와 :validate로 HARNESS 기준 충족 여부를 점검한다. README 스스로 “한 번 실행으로 전체 기능을 덮지 못하며 refine을 여러 번 돌려야 한다”, “프런티어급 모델이 필요하고 작은 모델은 불완전한 CLI를 만든다”고 한계를 적어 두었다.

HARNESS.md가 강제하는 원칙: ‘대체품을 만들지 마라’

하네스 한 개 해부: LibreOffice 예시

실제로 만들어진 하네스는 어떤 모양일까. 레지스트리 버전 1.0.1인 LibreOffice 하네스를 열어 보면 HARNESS.md의 구조가 그대로 보인다. 에이전트가 만지는 것은 .lo-cli.json이라는 프로젝트 JSON이고, 내보낼 때 하네스 자체 XML 빌더가 ODF 중간 파일을 만든 뒤 libreoffice --headless --convert-to에 넘긴다. 백엔드 래퍼는 shutil.which()로 실행 파일을 찾고, 셸 문자열이 아닌 인자 리스트로 subprocess.run()을 호출한다.

# 에이전트가 실제로 치는 명령 (박스에서 실행한 그대로)
cli-anything-libreoffice --json document new --type writer -n "MoricWorld smoke" -o report.lo-cli.json
cli-anything-libreoffice --json --project report.lo-cli.json writer add-heading -t "CLI-Anything 스모크"
cli-anything-libreoffice --json --project report.lo-cli.json writer add-paragraph -t "에이전트가 GUI 없이 만든 문서입니다."
cli-anything-libreoffice --json --project report.lo-cli.json writer add-table -r 3 -c 2
cli-anything-libreoffice --json --project report.lo-cli.json export render out.pdf -p pdf --overwrite
# → {"action":"convert","format":"pdf","method":"libreoffice-headless",
#    "libreoffice_version":"LibreOffice 25.2.3.2 ...","file_size":36064,...}

눈여겨볼 지점은 상태의 위치다. 문서 내용은 프로젝트 JSON에 저장되므로 명령을 한 줄씩 따로 실행해도 이어진다. 반면 undo/redo 스택은 세션 메모리에 있어서, 단발성 명령으로 session undo를 부르면 {"error": "Nothing to undo."}가 돌아온다. REPL 안에서 같은 작업을 하면 undo가 정상 동작한다. 에이전트 루프를 설계할 때 “되돌리기가 필요한 탐색적 편집은 REPL 세션으로, 확정 작업은 단발 명령으로”라는 구분이 필요하다는 뜻이다.

CLI-Hub: 103개 CLI를 다루는 패키지 매니저

하네스를 직접 생성하지 않고 이미 만들어진 것을 쓰려면 cli-hub가 입구다. 레지스트리 JSON을 GitHub Pages에서 받아 ~/.cli-hub/에 1시간 캐시하고, 항목의 설치 전략에 따라 pip·uv·npm·brew·번들·스크립트 설치를 대신 실행한다. 0.4.x에서는 여러 CLI를 작업 단위로 묶은 매트릭스가 더해졌다. 예를 들어 cli-hub can "subtitle"은 영상 매트릭스의 text.transcribe·text.caption 같은 역량별로 “지금 이 환경에서 무엇이 이미 되고 무엇이 빠졌는지”를 보여 준다.

설치와 실행: 세 가지 진입점

# 1) 이미 만들어진 CLI 쓰기 (분석 전송 끄고 시작하는 것을 권장)
export CLI_HUB_NO_ANALYTICS=1
pip install cli-anything-hub          # 0.4.1, Python 3.10+
cli-hub search office
cli-hub install libreoffice           # 실제 LibreOffice는 별도 설치 필요
cli-anything-libreoffice --help

# 2) 에이전트에게 허브 메타 스킬 쥐여 주기
npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill -g -y

# 3) 새 하네스 생성 (Claude Code 예시)
/plugin marketplace add HKUDS/CLI-Anything
/plugin install cli-anything
/cli-anything ./gimp                  # 소스 경로 또는 저장소 URL 필수
/cli-anything:refine ./gimp "batch processing and filters"

# 하네스 테스트 (설치된 명령 기준 검증 권장)
cd libreoffice/agent-harness && pip install -e .
CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/libreoffice/tests -q

박스 스모크 테스트: 실제로 돌려 본 결과

박스(리눅스, Python 3.13.5 venv)에서 격리된 HOME과 CLI_HUB_NO_ANALYTICS=1로 실행했다. 코딩 에이전트 로그인이나 LLM 호출은 하지 않았으므로 7단계 생성 자체는 검증 범위 밖이고, 대신 생성 결과물(하네스)과 허브·플러그인 구성을 검증했다. 박스에는 LibreOffice 25.2.3.2가 있고 GIMP는 없다.

GIMP 결과는 결함이 아니라 설계 그대로다. “진짜 소프트웨어는 필수 의존성”이라는 원칙 때문에 GIMP가 없으면 렌더 경로가 깔끔하게 실패하고 설치 방법을 알려 준다. 다만 pip install 기본 의존성(click, prompt-toolkit)만으로는 E2E 테스트 모듈이 import조차 안 된다는 점은 패키징 측면의 작은 흠이다. 실서비스에 쓰려면 pip install -e '.[pillow,dev]'처럼 extras까지 명시하는 편이 안전하다.

보안·신뢰 경계: 코드로 확인한 다섯 가지

라이선스: 루트는 Apache-2.0, 하위 패키지는 제각각

Apache-2.0과 MIT는 둘 다 관대한 라이선스라 내부 사용에는 큰 문제가 없지만, 하네스를 사내 배포물에 포함하거나 재배포한다면 어떤 라이선스·NOTICE를 따를지 패키지 단위로 확인해 두는 것이 좋다. 메타데이터 불일치는 이슈로 정리를 요청할 만한 부분이다.

비교: 비슷한 접근과 어디가 다른가

요약하면 CLI-Anything은 “앱 내장 스크립팅”과 “MCP 서버”의 중간을 자동화한 것이다. 앱의 스크립팅 기능과 네이티브 파일 포맷을 쓰되, 그걸 매번 즉석에서 쓰지 않고 테스트된 명령 집합으로 한 번 굳혀 두는 방식이다. GUI 에이전트를 완전히 대체한다는 README의 주장은 소스가 있는 오픈소스 앱에서는 설득력이 있지만, 바이너리만 있는 상용 앱에서는 README 스스로 품질이 크게 떨어진다고 인정한다.

트레이드오프와 주의점

누가 도입하면 좋은가

정리

CLI-Anything의 진짜 기여는 “아무 앱이나 에이전트가 쓴다”는 슬로건보다 HARNESS.md라는 설계 규약에 있다. 대체 구현 금지, 네이티브 포맷을 데이터 계층으로, 출력은 측정으로 검증, 모든 명령에 JSON, REPL과 세션 잠금, 프리뷰 번들까지 — 에이전트가 쓰기 좋은 CLI의 조건을 이만큼 구체적으로 적은 문서는 드물다. 박스에서 돌려 본 LibreOffice 하네스는 180개 테스트를 통과했고, 한글 문서를 1.5초 안에 PDF로 만들어 냈다. 반면 cli-hub는 원격 레지스트리의 설치 명령을 고정 없이 실행하고 분석을 기본으로 켜 두는 등, 편의를 위해 신뢰를 넓게 잡은 부분이 있다. 규약과 하네스는 적극적으로 가져다 쓰고, 허브의 설치·분석 경로는 내 기준으로 좁혀 쓰는 것이 지금 시점의 합리적인 사용법이다.