octo-cli

octo-cli is the command-line interface for the Octo ecosystem — a thin, single-binary REST client designed for AI Agent Bots to call via exec from agent runtimes (OpenClaw, Claude Code, and similar). Every invocation emits a structured JSON envelope on stdout; errors go to stderr with a deterministic taxonomy. There is no interactive I/O.

Architecture

octo-cli is metadata-driven. The command tree is auto-registered at startup from OpenAPI 3.x specs embedded into the binary. Adding or changing an endpoint means editing a spec, not the code.

OpenAPI specs  ──►  Registry  ──►  Service Engine  ──►  Factory  ──►  Client  ──►  Output
(embedded)         (parsed)       (cobra commands)    (DI)          (HTTP)       (envelope)

Key properties:

• Thin client. All business logic lives in backend services (matters, dmworkim). The CLI is transport, validation, and formatting.
• Unified gateway routing. Each operation declares its complete module-qualified path and uses OCTO_API_BASE_URL.
• Factory DI. internal/cmdutil.Factory is the dependency container. No mutable package-level globals; tests inject stubs through ConfigFunc / CredentialFunc / ClientFunc / RegistryFunc.
• Agent-first output. A stable JSON envelope with identity, data, pagination, and rate-limit metadata; a small fixed error taxonomy.

Domains

Installation

npm

For Node-based agent runtimes (OpenClaw, etc.):

npm install -g @mininglamp-oss/octo-cli

The npm package resolves the matching platform sub-package, which already contains the prebuilt binary. Install does not download binaries from GitHub.

Go install

go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest

Homebrew (coming soon)

brew install Mininglamp-OSS/tap/octo-cli

GitHub Releases

Download the latest binary for your platform from GitHub Releases:

# Archives are named octo-cli_<version>_<os>_<arch>.tar.gz for every platform,
# including Windows. Pick the one for your platform and substitute <version>
# (e.g. 0.5.0):
curl -LO https://github.com/Mininglamp-OSS/octo-cli/releases/download/v<version>/octo-cli_<version>_linux_amd64.tar.gz
tar xzf octo-cli_<version>_linux_amd64.tar.gz
sudo mv octo-cli /usr/local/bin/

Windows release archives are .tar.gz as well; Windows 10+ includes tar.exe.

install.sh

curl -fsSL https://raw.githubusercontent.com/Mininglamp-OSS/octo-cli/main/install.sh | sh

Quick Start

# Authenticate as a bot.
export OCTO_BOT_TOKEN="bf_your_user_bot_token"
# Optional for test or self-hosted deployments; production is the default.
# export OCTO_API_BASE_URL="https://im-test.deepminer.com.cn"

# NOTE: the `matter` domain is temporarily withheld (backend API stabilizing).

# Messaging
octo-cli message send --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'
octo-cli message edit --data '{"message_id":"m-1","channel_id":"chat-1","channel_type":1,"content_edit":"{\"type\":1,\"content\":\"updated\"}"}'

# Message search (User Bot bf_ or user API key uk_ token; App Bot app_ is rejected locally).
octo-cli message search --chat-id chat-1 --keyword "quarterly report"   # in-channel
octo-cli message search --keyword "quarterly report"                    # cross-channel (mixed feed)
octo-cli message search files --chat-id chat-1 --keyword "*.pdf"        # files in a channel
octo-cli message search groups --keyword "quarterly report"            # which channels matched (L1)
octo-cli message search all --keyword "budget" --on-behalf-of u-alice  # OBO: as a real person

# Groups and threads
octo-cli group list
octo-cli group members group-abc
octo-cli thread list group-abc
octo-cli thread create group-abc --name "design review"

# Files
octo-cli file upload --file ./report.pdf
octo-cli file download abc123 --jq '.data.url'

# Agent Mail — policy-aware send; the server may accept it or save a Draft
# depending on the mailbox's current outbound mode.
octo-cli mail message send-intent \
  --to recipient@example.com --subject "Status update" --text "Ready." \
  --idempotency-key "send-example-001"
octo-cli mail thread get T123
octo-cli mail draft list
# Draft update replaces the entire Draft. Read it first and resend every field
# that must remain; omitted cc/bcc/text/html/attachments are removed.
octo-cli mail message read E123
octo-cli mail draft update E123 --draft-version 1 \
  --to recipient@example.com --cc teammate@example.com \
  --bcc archive@example.com --subject "Updated draft" --text "Updated body"
# Retaining attachments requires a complete attachments array containing the
# exact base64 content, supplied through --data.

# Send an ordinary human-authored Draft without --draft-version.
octo-cli mail draft send E120
# Send an Agent-prepared Draft with its current version.
octo-cli mail draft send E124 --draft-version 2
octo-cli mail draft delete E125

# Docs — create/list/search, then read and incrementally edit the live body.
octo-cli docs create --title "Design notes"
octo-cli docs list --sort updatedAt:desc
octo-cli docs search --keyword "quarterly plan" --doc-type doc --page-all
octo-cli docs get doc-123
octo-cli docs content get doc-123          # returns the body + base version token
octo-cli docs import doc-123 --file ./notes.md      # replaces a doc from .md/.markdown/.docx
octo-cli docs export doc-123 --export-format pdf -o ./notes.pdf
# PPT: use the dedicated live revision API; preserve all fields when editing.
octo-cli docs create --docType html_ppt --title "Quarterly Review" --templateId signal --idempotency-key <unique-key>
# Native gallery: signal, terra, orbital, picnic; requires the matching backend catalogue.
# The server clones a template; the agent fills it through docs ppt get/edit (see skills/octo-docs/ppt.md).
octo-cli docs ppt get ppt-7
octo-cli docs ppt edit ppt-7 --data @edit.json   # {"baseRevision":7,"deck":{...}}
octo-cli docs ppt get ppt-7                    # read back to verify the change
octo-cli docs ppt export ppt-7 --file-format html --output slides.html
# Anchors, comment replies, versions and restore: skills/octo-docs/ppt.md.
# Boards: portable export and point/element comments.
octo-cli docs scene export board-7 --image-format excalidraw -o ./board.excalidraw
octo-cli docs comments add board-7 --body "Review this" --point 120,240
# For --element-id anchors, dry-run still reads the live board scene to resolve geometry.
octo-cli docs members set doc-123 --uid u-1 --role writer
# Member mutations are Space-qualified. Set defaults to the authenticated Bot
# Space when omitted; removal always requires the exact principal Space.
octo-cli docs members set doc-123 --uid u-1 --role writer --principal-space-id space-2
octo-cli docs members remove doc-123 u-1 --principal-space-id space-2

# Fleet/Loop uses the same gateway under /fleet/api/v1.
octo-cli loop task list --workspace-id <workspace-id>
octo-cli docs comments add doc-123 --data '{"body":"looks good"}'

# HTML documents registered in docs-backend use the same search endpoint.
# Resolve a hit's HTML document reference with docs get, then continue in the separate html domain.
octo-cli docs search --keyword "interactive roadmap" --doc-type html --page-all
octo-cli docs get html-doc-id              # returns octoDocSlug for HTML documents
octo-cli html get <octoDocSlug>

# Spreadsheets — read the live cells