octo-cli
A command-line client for the Octo ecosystem built for AI agents: messages, documents, drive and mail through commands that answer in JSON
- 920 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Sends messages and mail and edits and deletes documents, spreadsheets and files in the name of a bot or a real person (the `uk_*` token, the `--on-behalf-of` parameter)
- Stores profiles and tokens in the `~/.octo-cli` directory and reads them from environment variables
- Goes to the Octo server over the network, and the `octo-cli api` command calls any method of its gateway
Install
- Works in
Manual install
npm install -g @mininglamp-oss/octo-cliThe package pulls a sub-package with a ready binary for your platform and does not download it from GitHub.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Sends messages and mail and edits and deletes documents, spreadsheets and files in the name of a bot or a real person (the `uk_*` token, the `--on-behalf-of` parameter)
- Stores profiles and tokens in the `~/.octo-cli` directory and reads them from environment variables
- Goes to the Octo server over the network, and the `octo-cli api` command calls any method of its gateway
This is third-party code. Review the repository files before installing.
What it does
octo-cli is a single Go executable through which an agent calls the REST API of the Octo ecosystem with shell commands. It installs with `npm install -g @mininglamp-oss/octo-cli`, `go install github.com/Mininglamp-OSS/octo-cli/cmd/octo-cli@latest`, the `install.sh` script or an archive from the releases. There is no sign-in for a person: authorization uses a bot token from `OCTO_TOKEN` or `OCTO_BOT_TOKEN`. The command tree is built at startup from embedded OpenAPI specs, so new methods arrive with updated specs rather than code. Commands are split into domains: `message` (send, edit, search), `group`, `thread`, `file`, `drive` (network drive), `docs` (documents, spreadsheets, whiteboards and slides), `html` (interactive HTML documents), `mail` (agent mail), `bot`, `event` and `loop` (managing tasks and executors). Before editing a spreadsheet or a board, the command first reads the content together with a version token, and the edit carries that token so other people's changes are not overwritten. A method missing from the tree is called with `octo-cli api GET /v1/...`. Every successful call prints JSON on stdout with the fields `ok`, `identity`, `data`, pagination and rate limit details, and errors go to stderr with exit code 3 for authorization, 2 for validation and 1 for everything else. The `--dry-run`, `--jq`, `--page-all` and `--format` flags show the request, pick a field and walk the pages. Instructions for agents are embedded in the binary: `octo-cli skills` lists them and `octo-cli skills --install <directory>` writes all skills with their reference files.
Who it is for. For teams already working in the Octo ecosystem that want to give an agent (Claude Code, OpenClaw and similar) control of messages, documents, drive and mail through a bot token.
Good fit when
- The agent has to send and search messages in Octo chats, groups and threads: `octo-cli message search` searches one channel or all of them
- You need to read and edit Octo documents, spreadsheets and boards without overwriting other people's changes: the command returns a version token and accepts it on edit
- You need to check a request before sending it: `--dry-run` prints it and sends nothing
- The agent needs a built-in guide to a domain: `octo-cli skills octo-mail` prints the agent mail guide
- A document or a spreadsheet has to be exported to a file: `octo-cli docs export <id> --export-format pdf -o file`
Not a fit when
- You have no Octo account and token: the client has no interactive sign-in
- You need a client for Lark or Feishu: there is a separate lark-cli for them
- You want a dialogue with confirmations for a person: the client asks no questions and reads no input
- You need the `matter` domain with tasks or `summary` with digests: the author withheld them for now while the backend stabilizes
Example request
Find messages in Octo chats containing the words "quarterly report" and create a document listing the files foundLimitations
- Four token kinds are accepted: `app_*`, `bf_*`, `uk_*` and `octo_loop_*`. The client does not check rights locally, and the server answers `FORBIDDEN`. A bot with an `app_*` token cannot write to groups, work with threads or search messages.
- By default the client talks to `https://im.deepminer.com.cn`, and another address is set with the `OCTO_API_BASE_URL` variable. Profiles and tokens are stored in the `~/.octo-cli` directory.
- For Loop tasks in `OCTO_CREDENTIAL_MODE=task` a trimmed command set is available. The author stresses that this mode does not protect against a process that can change its own environment.
- Updating a mail draft replaces it entirely: omitted cc, bcc, text, html and attachment fields disappear. The `docs import --mode replace` command overwrites a board.
- Installation through Homebrew is marked as coming soon. License Apache-2.0.
How to disable. Remove the binary with `npm uninstall -g @mininglamp-oss/octo-cli` or delete the `octo-cli` file from the install directory. Drop the token from `OCTO_TOKEN` and `OCTO_BOT_TOKEN`, and delete saved profiles together with the `~/.octo-cli` directory.
FAQ
Which tokens does octo-cli accept?
An app bot token `app_*`, a user bot token `bf_*`, a user key `uk_*` for search and drive and short-lived Loop task credentials `octo_loop_*`. The `OCTO_TOKEN` variable wins over `OCTO_BOT_TOKEN`, and the `identity.source` field of the reply shows which one was used.
How do I list operations without the network?
The OpenAPI specs are embedded in the binary: `octo-cli schema --list` lists all operations, `octo-cli schema --list message` one domain, and `octo-cli schema message.send` shows the request and response schema.
How do I avoid overwriting other people's edits in a spreadsheet?
First `octo-cli docs sheet get <id>` returns the cells and a version token, then `docs sheet edit <id> --base-version "<token>" --data ...` edits under that token. The server rejects row and column inserts and deletes for workbooks with formulas.
What happens to a message after send-intent?
The command respects the mailbox policy: the server may accept the message for sending or save it as a draft, depending on the current outbound mode. A draft prepared by an agent is sent with `mail draft send` and its version.
How do I get all pages of a list at once?
Add `--page-all`: the client walks the pages while there is a continuation and returns one merged array. `--page-limit` sets the cap, 10 pages by default.
How do I point it at another Octo server?
Use the `OCTO_API_BASE_URL` variable or `octo-cli auth update --api-base-url <address>` for the active profile. The address must be a gateway origin like `http(s)://host[:port]` with no path, query or credentials.
Discussion
No questions or reviews yet.
Related
CLI toolsLark CLI
lark-cli
The official Lark and Feishu CLI with agent skills: messages, docs, sheets, calendar, mail and tasks from the terminal, over 200 commands
A Slack CLI and skill: the agent reads channels and threads and searches messages and files, and drafts or sends only when you ask
DingTalk Workspace CLI (dws)
DingTalk Workspace CLI
Official DingTalk CLI with agent skills: chats, calendar, todos, mail, docs and approvals of your organization from the terminal
Jira MCP in Go: an agent searches issues by JQL, runs sprints, comments and worklogs and sees an issue's branches and pull requests on Cloud and Server
Agent Client for Obsidian
Agent Client
An Obsidian plugin that runs Claude Code, Codex and other agents via the Agent Client Protocol right inside your notes vault
Pachca API skills and CLI
Пачка API
Official agent skills and CLI for the Pachca corporate messenger: messages, chats, users, bots, tasks and search
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| octo-cli (this entry) | yes | 920 | |
| Lark CLI | yes | 17,789 | the official Lark and Feishu CLI with skills for agents: messages, documents, calendar, mail and tasks |
| DingTalk Workspace CLI (dws) | yes | 3,775 | the official DingTalk CLI with skills for agents: chats, calendar, tasks, mail and organization documents |
README in short
The repository documentation describes how the client is built: OpenAPI specs, a registry, a command engine and a network layer. It continues with a table of domains, four installation methods, examples for messages, mail, documents, spreadsheets, boards and HTML, an authorization section with a table of token kinds, a list of environment variables, the reply format and exit codes. A separate section lists the agent skills in `skills/`. Next to it are the sources in `cmd` and `internal`, an npm wrapper, a changelog and contribution rules.