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, Bun or pnpm

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

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

# Or use the global package manager for your runtime:
bun install -g @mininglamp-oss/octo-cli
pnpm add -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

Upgrade a global package installation

octo-cli upgrade --dry-run
octo-cli upgrade

upgrade identifies the npm, Bun or pnpm installation that owns the invoked command and updates it to the configured registry's stable latest release. An equal or newer installed version is a successful no-op. It verifies the installed package, platform binary and command before reporting success.

Updates enable optional dependencies for npm/pnpm and explicitly install Bun's matching platform package, because its executable is required to run the CLI.

Registry mirrors, scoped registries and authentication use the owning manager's native settings: npm's user/global .npmrc and environment, Bun's supported .npmrc and global .bunfig.toml, or pnpm's native configuration. The invoking project's registry settings do not redirect the upgrade.

Dry run checks local ownership without contacting a registry or installing. Upgrade requires no Octo credentials and preserves --format / --jq. Use the original installation method for raw binaries, go install, project-local or temporary installs. Loop task mode does not allow upgrades. Package-manager failures stop the command; an installation failure can leave partially changed files, so inspect the structured error before retrying.

Quick Start

# Authenticate as a bot (`OCTO_BOT_TOKEN` remains a compatible alias).
export OCTO_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'

# Drive — the server chooses single-part or multipart upload; the same command
# handles both. Its single prepare request declares multipart-v1; the server
# returns `single` below its threshold or a multipart snapshot above it.
# Multipart progress goes to stderr.
octo-cli drive upload file ./large.bin --space-id <drive-space-id>

# 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 -