Mininglamp-OSS/octo-cli

octo-cli – Octo AI 에이전트 생태계를 위한 가벼운 JSON 우선 CLI

무엇인가요 – octo-cli는 Go로 작성된 단일 바이너리 명령줄 클라이언트로, Octo 플랫폼의 REST API와 통신합니다. AI 에이전트 런타임(예: OpenClaw, Claude Code)이 exec를 통해 호출하도록 설계되었습니다. 모든 호출은 stdout에 결정론적인 JSON 엔벨로프를 반환합니다. 오류는 stderr에 고정된 분류 체계를 가진 JSON으로 출력됩니다. 인터랙티브 프롬프트는 존재하지 않으며, 이 도구는 순수하게 프로그래밍 방식입니다.

왜 존재하는가 – 모든 비즈니스 로직은 Octo의 백엔드 서비스(문서 저장, 드라이브, 메시징, 플릿 제어 등)에 있습니다. CLI의 역할은 다음과 같습니다:

• 바이너리에 내장된 OpenAPI 3.x 사양을 읽기
• 자동으로 코바(Cobra) 기반의 명령 트리를 생성하기
• 네트워크 호출 전에 요청 페이로드를 사양에 따라 검증하기
• HTTP 요청 보내기
• 응답을 표준 엔벨로프 형식으로 포맷하기

핵심 설계 요소

기능	세부 사항
메타데이터 기반	엔드포인트는 내장된 OpenAPI 사양에만 정의됨. API를 추가하는 것은 Go 코드 변경이 아니라 사양 편집만으로 가능.
에이전트 우선 출력	ok, identity, data, 페이징 및 레이트 제한 정보를 포함하는 안정적인 JSON 엔벨로프.
의존성 주입	내부 Factory가 설정, 자격 증명, HTTP 클라이언트, 사양 레지스트리를 제공 – 테스트가 쉬움.
결정론적 오류	검증 오류는 로컬에서 포착됨. 백엔드 거부는 고정된 type/code 스키마로 반환됨.
경량 클라이언트	비즈니스 로직 없음. CLI는 단지 전송, 검증, 포맷만 담당.

지원되는 도메인 – CLI는 도메인별로 그룹화된 다양한 작업을 노출합니다(각 도메인은 백엔드 서비스에 대응):

• docs – 라이프사이클, 전체 텍스트 검색, 스프레드시트, 화이트보드, 댓글, 버전, 첨부 파일.
• html – 변경 불가능한 인터랙티브 HTML 문서, 드래프트, 공유 코드, UID별 권한 부여.
• drive – 네트워크 드라이브 공간, 폴더 트리, 2단계 블롭 업로드, 서명된 다운로드, 공유 링크.
• group, thread, message, file, event – 협업 기초 구성 요소.
• bot – 봇 등록, 허트비트, 사용자 정보.
• loop – 플릿 제어 플레인(작업, 실행, 전문가, 자동화 등).
• matter, summary – 백엔드 안정화 중이므로 일시적으로 비활성화됨.

설치

• npm – npm install -g @mininglamp-oss/octo-cli (호스트 플랫폼용 사전 빌드된 바이너리 다운로드).
• Go – go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest.
• Homebrew – 계획 중 (brew install Mininglamp-OSS/tap/octo-cli).
• GitHub 릴리스 – OS/아키텍처에 맞는 tarball을 다운로드하고 $PATH에 있는 디렉터리로 바이너리 이동.
• install.sh – 최신 릴리스를 가져오는 원라인 curl 스크립트.

일반적인 워크플로우 (환경 변수로 인증 및 라우팅 제어):

export OCTO_BOT_TOKEN="bf_…"          # 봇 토큰 (app_, bf_, uk_, 또는 octo_loop_)
# 선택 사항: export OCTO_API_BASE_URL="https://im-test.deepminer.com.cn"

# 봇에서 메시지 전송
octo-cli message send \
  --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'

# 채널 간 메시지 검색
octo-cli message search --keyword "quarterly report"

# 그룹 목록 보기, 스레드 생성
octo-cli group list
octo-cli thread create group-abc --name "design review"

# 드라이브에 파일 업로드
octo-cli file upload --file ./report.pdf

모든 명령어는 --format (json|table|csv|ndjson), --jq (후처리용), --dry-run (해결된 요청 보기), --verbose (요청/응답 로그), 페이징 헬퍼 (--page-all, --page-limit)와 같은 유니버설 플래그를 수용합니다.

인증 모델 – 봇 전용. CLI는 우선순위 순서로 토큰을 읽습니다:

1. 저장된 프로필 (octo-cli auth login)
2. OCTO_TOKEN
3. OCTO_BOT_TOKEN 토큰 유형은 App 봇(app_*), User 봇(bf_*), 사용자 API 키(uk_*), Loop 작업 자격(octo_loop_*) 중 하나입니다. 토큰 유형에 따라 백엔드가 허용하는 기능이 결정되며, CLI는 몇 가지 프리플라이트 체크(예: app_*로 메시지 검색 거부)를 수행합니다.

출력 형식 – 성공적인 호출은 다음과 같은 형식으로 출력:

{ "ok": true, "identity": "bot", "data": {…}, "_pagination": {…}, "_rate_limit": {…} }

실패 시 stderr에 error.type, code, message, 선택적 hint/detail를 포함한 유사한 엔벨로프를 출력합니다. 종료 코드: 3 (인증), 2 (검증/설정), 1 (기타).

에이전트 기술 – 인간이 읽을 수 있고 기계가 파싱할 수 있는 기술 파일은 skills/ 디렉터리에 있습니다. 각 도메인의 명령어, 플래그, 오류 분류 체계를 설명하여 AI 에이전트가 런타임에 로드할 수 있도록 합니다(octo-cli skills). 파일은 바이너리 내에 내장되어 오프라인에서도 사용 가능합니다.

확장성 – 엔드포인트 추가 또는 변경은 internal/registry/specs/ 아래의 OpenAPI 사양 파일을 편집하여 수행합니다. CLI는 시작 시 명령 트리를 재생성합니다. Go 소스 변경은 필요 없습니다.

라이선스 – Apache-2.0.

---

결론 – octo-cli는 목적에 맞게 설계된 비대화형 CLI로, AI 에이전트가 Octo 플랫폼과 예측 가능하고 JSON 중심의 방식으로 상호작용할 수 있도록 하며, 내장된 스키마 검증, 페이징, 풍부한 협업 API를 제공합니다.