octo-cli: a metadata-driven REST client for AI agent bots

The problem octo-cli solves for agent runtimes

An agent runtime that wants to send a chat message, upload a file or search documents has two options: speak HTTP directly, or shell out to a tool. Speaking HTTP means every agent author reimplements authentication, pagination and error handling, and the agent has to parse a response body that was designed for a browser, not a program. octo-cli takes the second path. It is described in the README as "a thin, single-binary REST client designed for AI Agent Bots to call via exec from agent runtimes (OpenClaw, Claude Code, and similar)."

The target user is not a human at a terminal. Every invocation writes a structured JSON envelope to stdout, errors go to stderr with what the README calls "a deterministic taxonomy", and there is no interactive I/O. That last property matters more than it sounds: a CLI that prompts for a password or asks for confirmation will hang an agent loop until a timeout fires. octo-cli removes that class of failure by design.

The project is written in Go and licensed under Apache-2.0. It is not a general-purpose HTTP client. All business logic lives in backend services, and the README is explicit that the CLI is "transport, validation, and formatting". If you are looking for a tool that computes anything locally, this is the wrong layer.

How the metadata-driven registry turns specs into commands

The architecture is the interesting part. The command tree is not hand-written per endpoint. It is auto-registered at startup from OpenAPI 3.x specs embedded into the binary, so adding or changing an endpoint means editing a spec rather than the Go code. The README draws the pipeline as specs into a registry, the registry into a service engine that produces cobra commands, then a factory, an HTTP client and the output envelope.

Two consequences follow. First, the binary carries its own API surface, so the command list and the spec version cannot drift apart at runtime. Second, the Makefile help text gives the extension recipe directly: create internal/registry/specs/<domain>.json as an OpenAPI 3.x document, embed it, and it auto-registers. That is a low-friction path for a team that already maintains OpenAPI documents for its services.

Dependency injection is handled by internal/cmdutil.Factory, which the README calls "the dependency container". The stated property is no mutable package-level globals, with tests injecting stubs through ConfigFunc, CredentialFunc, ClientFunc and RegistryFunc. That is a testability decision, and it is the kind of thing that shows up in go.mod: the only direct dependencies are gojq, cobra and golang.org/x/term. A CLI with three direct dependencies is small enough to audit.

Routing is unified. Each operation declares its complete module-qualified path and uses OCTO_API_BASE_URL, which is why a self-hosted or test deployment can be pointed at with one environment variable.

Installing octo-cli and sending a first message

There are four installation paths in the README. For Node-based agent runtimes, npm is the intended route, and the package resolves a platform sub-package that already contains the prebuilt binary. Install does not download binaries from GitHub.

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

If you have a Go toolchain, you can install from source instead. This builds the current tagged module version.

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

The README also documents a curl-based install.sh and manual download from GitHub Releases, where archives are named octo-cli_<version>_<os>_<arch>.tar.gz for every platform including Windows. Homebrew is listed as coming soon, which means the brew command in the README is not yet a working install path.

Once the binary is on PATH, authentication is a single environment variable. The README uses a user bot token with the bf_ prefix.

export OCTO_BOT_TOKEN="bf_your_user_bot_token"

For test or self-hosted deployments you also set OCTO_API_BASE_URL; production is the default. The README's example points at https://im-test.deepminer.com.cn. Then a first real call:

octo-cli message send --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'

What you should see is a JSON envelope on stdout. Note that the payload is passed as a JSON string through --data rather than as individual flags, so an agent constructing the call has to serialize the body itself. Also note the README's warning that the matter domain is temporarily withheld while the backend API stabilizes, so commands under that domain are not a safe first test.

Domain coverage and the operations that are withheld

The README's domain table is the most useful page in the repository, partly because it is honest about what does not work. docs carries 32 operations for documents, spreadsheets and whiteboards. html carries 20 for interactive HTML documents and is explicitly a separate backend from docs. drive is the largest shipping domain at 43 operations plus three composite commands for 46 leaves, covering spaces, the folder and file tree, two-phase blob upload, signed download and share links. loop is listed at 126 operations and described as a fleet control plane spanning tasks, executions, experts, workspaces, runtimes, projects, skills and automations.

Then there are the gaps. matter, at 14 operations for todos and tasks, is "temporarily withheld" while the backend API stabilizes. summary, at 4 operations, is withheld until the create backend in Mininglamp-OSS/octo-smart-summary#181 is merged, deployed and enabled. Neither has a published date for restoration. If your agent's job is task management or summarization, octo-cli is not the right tool right now, regardless of how well the rest of it fits.

There is a second, subtler constraint in the messaging examples. Message search requires a User Bot bf_ token or a user API key uk_ token, and the README states that an App Bot app_ token is rejected locally. So token type is not interchangeable across the command tree, and a deployment using app_ tokens will find search unavailable even though send works.

The mail commands introduce a third behavior worth knowing before you build on them. mail message send-intent is policy-aware: the server may accept the send or save a Draft depending on the mailbox's current outbound mode. An agent that assumes a sent message was delivered will be wrong some of the time. Draft update has its own trap, documented in the README: it replaces the entire Draft, so omitted cc, bcc, text, html or attachments are removed. The README's own guidance is to read the draft first and resend every field that must remain.

What octo-cli does not tell you

The README is a good map of the command surface and a weak operations manual. Several things an adopter needs are simply absent. There is no documented rollback or downgrade procedure, so if a release changes an envelope field your agent depends on, the README does not describe how to pin or revert. The error taxonomy is described as deterministic but the actual error codes are not enumerated in the README, which means you cannot write a switch statement over them without reading the source or the specs.

The envelope is said to carry identity, data, pagination and rate-limit metadata, but the README does not show a full example envelope, so the field names for pagination and rate limits have to be discovered from real output. That is a small friction for a human and a larger one for an agent that needs to branch on a rate-limit signal.

Pagination is mentioned in the architecture description and in the docs domain entry, which notes sheet cells are a paged read, but the README does not document the flag or parameter that advances a page. If your workflow reads large document sets, plan to inspect the generated help for the specific operation rather than relying on the README.

Finally, the withheld domains are a moving target. The README says matter is withheld "while the backend API stabilizes" and summary is withheld pending a specific upstream merge. Nothing in the repository states when either returns, so any plan that assumes they will be available on a given date is a guess.

octo-cli compared with calling the REST API directly

The obvious alternative is not another CLI. It is writing the HTTP calls yourself, either directly from the agent runtime or through a thin internal wrapper. The difference in approach is where the API surface lives. With a hand-written wrapper, the endpoint list lives in your code, and it drifts from the backend whenever a service team ships a change. With octo-cli, the endpoint list lives in embedded OpenAPI 3.x specs, and the command tree is regenerated from them at startup.

That trade is real in both directions. You gain a maintained, versioned command surface and a consistent JSON envelope across domains, plus a fixed error taxonomy instead of per-service error shapes. You give up control over the transport layer. If you need custom retry logic, request signing, or a response transformation that the envelope does not support, you are working around the CLI rather than with it. The README's own framing supports this: the CLI is "transport, validation, and formatting", and everything else belongs to the backend.

A second alternative is the Go client library. The project publishes to pkg.go.dev at github.com/Mininglamp-OSS/octo-cli, so a Go-based agent could import the packages instead of shelling out. That avoids process spawn overhead and gives you typed access, but it only helps if your runtime is written in Go. For the Node-based runtimes the README names, the npm package is the intended path, and there is no equivalent library binding documented for those environments.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-10. Releases have been frequent and regular: v0.13.0 on 2026-08-24, v0.14.0 on 2026-08-31, and v0.15.0 on 2026-09-08. That cadence, combined with the fact that all three recent releases are v0.x, tells you the project is still settling its interface. A minor version bump in a v0.x line can carry a breaking change, and the README does not describe a deprecation policy or a stability guarantee for the envelope schema.

Upgrade cost is therefore mostly about the envelope contract. Because the command tree is generated from embedded specs, upgrading the binary also upgrades the API surface it exposes. If a spec change renames an operation or alters a field your agent reads, the failure appears at runtime in your agent, not at build time. The practical mitigation is to pin a version in your npm or Go install and test the specific operations you depend on before moving the pin.

On licensing, the project is Apache-2.0, which is a permissive licence that includes an explicit patent grant. That is a different posture from a copyleft licence and generally easier to adopt inside a commercial product. The npm package name carries the @mininglamp-oss scope and the Go module path is github.com/Mininglamp-OSS/octo-cli, so the published artifacts are traceable to the same organization. This is a description of the licence identifier and packaging, not legal advice; review the LICENSE file and your own obligations before shipping.

Editorial conclusion

Adopt octo-cli if you run an agent runtime that shells out to a CLI and you want a stable JSON envelope instead of parsing HTTP responses yourself. Do not adopt it if you need the matter or summary domains today, or if your runtime cannot set OCTO_BOT_TOKEN in the environment. Before wiring it in, verify three things: which domains are actually enabled in your deployment, whether your bot token type is accepted for the operations you plan to call, and how the envelope reports rate-limit metadata.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Mininglamp-OSS/octo-cli on GitHub
3. Project website
4. README
5. Releases