Mininglamp-OSS/octo-cli

octo‑cli – a thin, JSON‑first CLI for the Octo AI‑agent ecosystem

What it is – octo-cli is a single‑binary command‑line client written in Go that talks to the Octo platform’s REST APIs. It is meant to be invoked by AI‑agent runtimes (e.g., OpenClaw, Claude Code) via exec. Every call returns a deterministic JSON envelope on stdout; errors are printed as JSON on stderr with a fixed taxonomy. There is no interactive prompt – the tool is purely programmatic.

Why it exists – All business logic lives in Octo’s backend services (document storage, drive, messaging, fleet control, etc.). The CLI’s job is to:

• read OpenAPI 3.x specs that are baked into the binary,
• generate a Cobra‑based command tree automatically,
• validate request payloads against the specs before any network call,
• send HTTP requests, and
• format the response into the standard envelope.

Key design points

Feature	Detail
Metadata‑driven	Endpoints are defined only in embedded OpenAPI specs; adding an API is a spec edit, not Go code.
Agent‑first output	Stable JSON envelope containing ok, identity, data, pagination and rate‑limit info.
Dependency injection	Internal Factory provides config, credentials, HTTP client, and spec registry – makes testing easy.
Deterministic errors	Validation errors are caught locally; backend rejections are returned with a fixed type/code schema.
Thin client	No business logic; the CLI is just transport, validation, and formatting.

Supported domains – The CLI exposes a large set of operations grouped by domain (each domain maps to a backend service):

• docs – lifecycle, full‑text search, spreadsheets, whiteboards, comments, versions, attachments.
• html – immutable interactive HTML docs, drafts, share codes, per‑UID grants.
• drive – network‑drive spaces, folder trees, two‑phase blob upload, signed download, share links.
• group, thread, message, file, event – collaboration primitives.
• bot – bot registration, heartbeat, user‑info.
• loop – fleet control plane (tasks, executions, experts, automations, etc.).
• matter, summary – listed but temporarily disabled while their backends stabilize.

Installation

• npm – npm install -g @mininglamp-oss/octo-cli (pulls a pre‑built binary for the host platform).
• Go – go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest.
• Homebrew – planned (brew install Mininglamp-OSS/tap/octo-cli).
• GitHub releases – download the tarball for your OS/arch and move the binary to a directory on $PATH.
• install.sh – one‑liner curl script that fetches the latest release.

Typical workflow (environment variables control authentication and routing):

export OCTO_BOT_TOKEN="bf_…"          # bot token (app_, bf_, uk_, or octo_loop_)
# optional: export OCTO_API_BASE_URL="https://im-test.deepminer.com.cn"

# Send a message from a bot
octo-cli message send \
  --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'

# Search messages across channels
octo-cli message search --keyword "quarterly report"

# List groups, create a thread
octo-cli group list
octo-cli thread create group-abc --name "design review"

# Upload a file to the drive
octo-cli file upload --file ./report.pdf

All commands accept universal flags such as --format (json|table|csv|ndjson), --jq for post‑processing, --dry-run to see the resolved request, --verbose for request/response logs, and pagination helpers (--page-all, --page-limit).

Authentication model – Bot‑only. The CLI reads a token from, in order of precedence:

1. Stored profile (octo-cli auth login)
2. OCTO_TOKEN
3. OCTO_BOT_TOKEN Tokens can be App Bots (app_*), User Bots (bf_*), user API keys (uk_*), or Loop task credentials (octo_loop_*). The token type determines which capabilities the backend will allow; the CLI performs a few pre‑flight checks (e.g., rejecting app_* for message search).

Output format – Successful calls emit:

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

Failures emit a similar envelope on stderr with error.type, code, message, and optional hint/detail. Exit codes: 3 (auth), 2 (validation/config), 1 (other).

Agent skills – Human‑readable, machine‑parseable skill files live under skills/. They describe each domain’s commands, flags, and error taxonomy so that AI agents can load them at runtime (octo-cli skills). The files are also embedded in the binary for offline use.

Extensibility – Adding or changing an endpoint is done by editing an OpenAPI spec file under internal/registry/specs/; the CLI regenerates the command tree at startup. No Go source changes are required.

License – Apache‑2.0.

---

Bottom line – octo-cli is a purpose‑built, non‑interactive CLI that lets AI agents interact with the Octo platform in a predictable, JSON‑centric way, with built‑in schema validation, pagination, and a rich set of collaboration APIs.