Octo CLI is the command-line client for the Octo ecosystem of messaging, documents, drive, mail, and fleet services. It is a single binary that AI agent bots call through exec from agent runtimes such as OpenClaw and Claude Code. Every call prints a structured JSON envelope on stdout, errors go to stderr with a fixed error taxonomy, and nothing prompts interactively.
The command tree is metadata-driven: it registers itself at startup from OpenAPI 3.x specs embedded in the binary, so adding or changing an endpoint means editing a spec rather than code. The CLI handles transport, validation, and formatting, and all business logic stays in the backend services behind one gateway. Validation of required fields, enum values, and id ranges happens locally before a request is sent.
Authentication is bot-only. A token identifies an App Bot, a User Bot, a user API key that acts as a real person (for message search and drive), or a short-lived Loop task credential, and the backend decides which operations each identity may run.
| Domain | Purpose |
|---|---|
| docs | Documents, spreadsheets, whiteboards, and slide decks: search, content reads, sheet edits, scenes, members, comments, versions |
| html | Interactive HTML documents published as immutable versions, with drafts, share codes, and element-level edits |
| drive | Network drive spaces, folder trees, search, uploads and signed downloads, share links |
| group, thread, message | Groups, threads, and messaging, including in-channel and cross-channel search |
| bot, file, event | Bot lifecycle, file transfer, and event polling |
| loop | Fleet control plane: tasks, executions, experts, workspaces, runtimes, skills, automations |
Features
- Agent-first output: a stable JSON envelope with identity, data, pagination, and rate-limit metadata, plus a small fixed error taxonomy and distinct exit codes
- Spec-driven commands: operations come from embedded OpenAPI specs, and a schema command lists every operation and its request and response shape offline
- Output formats: JSON, table, CSV, or NDJSON, with a jq expression applied to the envelope before formatting
- Dry runs: prints the resolved request instead of sending it
- Pagination: walks cursor-based list operations and emits one merged array, with a page cap
- Version-checked edits: spreadsheet, whiteboard, and slide edits read a base version and write against that version
- Agent Mail: policy-aware sends that the server either delivers or saves as a draft, plus draft and thread management
- Generic passthrough: calls API paths that are not auto-registered as commands
- Agent skills: usage docs for agents per domain (messaging, files, drive, docs, HTML, mail, marketplace), embedded in the binary
