octo-cli

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

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

brew install Mininglamp-OSS/tap/octo-cli

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

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

# 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 report --idempotency-key <unique-key>
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 + base version, then batch-edit under If-Match.
octo-cli docs sheet get sheet-9                      # whole sheet + base version token
octo-cli docs import sheet-9 --file ./report.xlsx    # imports the first visible worksheet
octo-cli docs export sheet-9 --export-format xlsx -o ./report.xlsx
octo-cli docs sheet get sheet-9 --limit 500          # page a large sheet; follow --cursor <nextCursor>
octo-cli docs sheet edit sheet-9 --base-version "<token>" \
  --data '{"cells":{"default!0:0":{"v":"hi"},"default!1:0":null}}'
# Structurally add/remove rows or columns and shift affected resources atomically.
# Coordinates are zero-based. The server refuses formula-bearing workbooks.
octo-cli docs sheet rows insert sheet-9 --base-version "<token>" \
  --logical-id default --after-row 9 --count 5
octo-cli docs sheet rows delete sheet-9 --base-version "<token>" \
  --logical-id default --start-row 10 --count 5
octo-cli docs sheet columns insert sheet-9 --base-version "<token>" \
  --logical-id default --after-column 3 --count 2
octo-cli docs sheet columns delete sheet-9 --base-version "<token>" \
  --logical-id default --start-column 4 --count 2

# Create a checkbox in A2 on a sheet that has no other validation rules.
# dataValidations.default replaces that sheet's complete rule set: otherwise first
# read sheetDataValidations and include every existing rule you need to keep.
octo-cli docs sheet edit sheet-9 --base-version "<token>" \
  --data '{"cells":{"default!1:0":{"v":0}},"dataValidations":{"default":[{"uid":"checkbox-a2","type":"checkbox","formula1":"1","formula2":"0","ranges":[{"startRow":1,"startColumn":0,"endRow":1,"endColumn":0}]}]}}'

# Whiteboards — read the live scene + base version, then upsert/delete elements under If-Match.
octo-cli docs scene get board-7                       # elements (z-order) + files + base version token
octo-cli docs scene edit board-7 --base-version "<token>" \
  --data '{"elements":[{"id":"e1","type":"rectangle","version":4}],"deletedElementIds":["e2"],"files":{}}'
octo-cli docs import board-7 --file ./board.excalidraw              # merge (default): preserves existing elements
octo-cli docs import board-7 --file ./board.excalidraw --mode replace # explicit overwrite; backend safety snapshot + concurrency protection
octo-cli docs export board-7 --export-format png -o ./board.png

# HTML docs (octo-doc) — a SEPARATE backend from `docs`. Publish self-contained
# interactive HTML as immutable versions, then edit a single stamped artifact.
# Canonical create has no doc reference: omit --slug. The CLI generates a key.
octo-cli html publish --html '<h1>hi</h1>' \
  --mount-type group --group-no <group_no> --data '{"meta":{"title":"Launch page"}}'
# Save data.slug from the publish response. For a new document data.slug == data.doc_id, mounted or
# unmounted. Every later operation uses data.slug. Old documents keep their legacy
# slug as data.slug; do not infer this from mount_type or doc_id being non-empty.
# To republish, pass --slug <doc-ref> and omit --idempotency-key. An unknown
# legacy slug is rejected and cannot create a document.
octo-cli html list
octo-cli html versions <doc-ref>
octo-cli html draft create --html '<h1>wip</h1>'
octo-cli html draft save <doc-ref> --data '{"html":"<h1>wip</h1>"}'   # then: html draft promote <doc-ref>
octo-cli html share <doc-ref>                                        # mint a reader share code
octo-cli html grant add <doc-ref> --data '{"uid":"u-1"}'             # per-uid authorization
octo-cli html element get --slug <doc-ref> --aid <content-hash>      # wire flag remains named slug
octo-cli html element replace --slug <doc-ref> --aid <content-hash> --new-html '<p>new</p>'

# Discover the API — fully offline, specs are embedded.
octo-cli schema --list              # all operations across all domains
octo-cli schema --list message      # operations in one domain
octo-cli schema message.send        # request/response schema for one op
octo-cli config show                # resolved config (token masked)
octo-cli auth update --api-base-url https://octo.example # persist endpoint for the active profile

# Generic passthrough for ops that aren't auto-registered.
octo-cli api GET  /v1/messages --params '{"chat_id":"chat-1"}'
octo-cli api POST /v1/messages --data @body.json

OCTO_TOKEN="$UK_KEY" octo-cli drive space list      # acts as the real person

{
  "ok": true,
  "identity": "bot",
  "data": { ... },
  "_pagination": { "has_more": true, "next_cursor": "..." },
  "_rate_limit": { "remaining": 99, "reset": 1730000000 }
}

{
  "ok": false,
  "error": {
    "type": "validation",
    "code": "VALIDATION_ERROR",
    "message": "title is required",
    "hint": "check params with `octo-cli schema <op>`",
    "detail": { ... }
  }
}

# Dry-run to inspect the resolved request — no side effects.
octo-cli message send --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"Hello"}}' --dry-run

# Extract a single field with jq.
octo-cli group list --jq '.data[0].id'

# Auto-paginate any list operation that reports a cursor.
octo-cli group list --page-all --page-limit 20

# Tabular output for human eyes.
octo-cli group list --format table

octo-cli skills                       # list embedded skills
octo-cli skills octo-mail             # load the official Agent Mail guide
octo-cli skills octo-docs             # print one skill (SKILL.md + its references)
octo-cli skills --install ~/.config/octo/skills   # write every skill (SKILL.md + references) to a dir

octo-cli completion bash   > /etc/bash_completion.d/octo-cli
octo-cli completion zsh    > "${fpath[1]}/_octo-cli"
octo-cli completion fish   > ~/.config/fish/completions/octo-cli.fish