Octo Shared

octo-shared — CLI fundamentals for AI Agents

octo-cli is a thin REST client that exposes the Octo ecosystem (matters, messaging, groups, threads, files, bot, events, docs, html) as a single binary. Every service command is auto-generated from an embedded OpenAPI registry; output is a JSON envelope designed to be parsed by agents.

The matter domain is temporarily withheld while its backend API stabilizes — octo-cli matter ... is not registered and the octo-matter skill is not listed. Do not emit matter commands until it is re-enabled. The examples below use other domains.

Bots cannot delete documents, even documents they created or own/administer. Do not invoke docs delete, html rm, or equivalent raw api DELETE calls to delete a document. Ask a human with document admin permission to delete it in Octo instead. Do not switch credentials/routes or clear the document's contents as a workaround. This rule concerns whole documents, not normal editing or otherwise-permitted comment, version, asset, or sheet row/column removal.

1. Authentication

Bots authenticate with a bearer token. There is no interactive user login — but besides the two bot tokens (app_*, bf_*) there is a third kind, a user API key (uk_*), which carries a real person's identity and is used mainly for message search. Two ways to supply any of them:

Stored profile (recommended). A human (or provisioning step) logs the token in once; it is encrypted at rest under ~/.octo-cli, and the raw token never appears in any command line, shell history, or transcript afterward:

bashCopy code
# Operator setup (token read from a hidden prompt, or --with-token < file):
octo-cli auth login --bot-id cli_xxxxxxxx          # robot id you got when creating the bot
echo "$TOKEN" | octo-cli auth login --bot-id cli_xxxxxxxx --with-token   # non-interactive

# A user API key (uk_) is stored the same way — encrypted profile, bot_kind shows
# user_key. Use a friendly --profile name since it has no robot id:
echo "$UK_TOKEN" | octo-cli auth login --profile alice-search --with-token

Then, at runtime, select which bot to act as — the agent passes its own robot id, which it knows:

bashCopy code
octo-cli --bot-id cli_xxxxxxxx matter list         # or env OCTO_BOT_ID=cli_xxxxxxxx
octo-cli --profile myname matter list              # or by the friendly profile name

With exactly one stored profile, the selector is optional. With two or more, you must pass --bot-id or --profile — omitting it is a hard error (the CLI never guesses which identity to use).

Env token (fallback). When no profile is stored, the raw token is read from OCTO_BOT_TOKEN:

bashCopy code
export OCTO_BOT_TOKEN=app_xxxxxxxxxxxxxxxxxxxx      # App Bot (DM-only)
export OCTO_BOT_TOKEN=bf_xxxxxxxxxxxxxxxxxxxxx       # User Bot (full access)
export OCTO_BOT_TOKEN=uk_xxxxxxxxxxxxxxxxxxxxx       # User API key (real person; message search)

OCTO_BOT_ID is a selector (a robot id), not a secret; OCTO_BOT_TOKEN is the secret. If OCTO_BOT_ID names no stored profile the command fails — it never falls back to silently using OCTO_BOT_TOKEN under that id.

Token prefix determines capability — the CLI does NOT enforce this locally (the backend rejects unsupported operations with FORBIDDEN), with one exception: an app_* token running message search is rejected locally with a validation error before any request.

uk_* carries a real person's identity and is meaningful mainly for message search (routed to /v1/user/*); for other domains use a bot token. bf_* can also search on behalf of a person with --on-behalf-of <uid>. identity.bot_kind reflects the kind: app_bot, user_bot, or user_key.

Outside OCTO_CREDENTIAL_MODE=task, inspect octo-cli auth status (or octo-cli config show) to confirm the active identity. Daemon task mode does not expose profile diagnostics; use the identity echoed by each success envelope and report authentication failures to the daemon instead (see §3).

2. Unified gateway configuration

All Octo domains use one gateway. Override it only for test or self-hosted deployments:

bashCopy code
# Production defaults to https://im.deepminer.com.cn. Override for test or
# self-hosted deployments:
export OCTO_API_BASE_URL=https://im-test.deepminer.com.cn

export OCTO_SPACE_ID=space_xxx                     # only for platform-scoped bots
export OCTO_FORMAT=json                            # default output format

Routing: all services go through OCTO_API_BASE_URL. The --service flag on octo-cli api is for documentation only — all traffic routes to the same gateway.

3. Output: the JSON envelope

Every successful invocation prints a single JSON object to stdout:

jsonCopy code
{
  "ok": true,
  "identity": { "type": "bot", "profile": "prod", "robot_id": "cli_xxx", "bot_kind": "app_bot", "source": "profile:prod" },
  "data": { ... or [...] },
  "_pagination": { "has_more": true, "next_cursor": "..." },
  "_rate_limit": { "remaining": 99, "reset": 1730000000 }
}

identity echoes the bot the command actually ran as — check it to catch acting as the wrong identity. It is always an object: a stored profile fills in profile / robot_id / source: "profile:<name>"; a raw OCTO_BOT_TOKEN yields { "type": "bot", "bot_kind": ..., "source": "env:OCTO_BOT_TOKEN" } (no profile/robot_id); a command that resolves no credential (e.g. version) yields the minimal { "type": "bot" }.

Every failure prints an error envelope to stderr and exits non-zero:

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

Parse ok first. On failure, branch on error.type (a small fixed taxonomy) or error.code (a string, may come straight from the backend).

error.code: bot_delete_forbidden (error.type: permission, HTTP 403) is a terminal policy denial, not missing membership or a transient error. Do not retry, request a higher bot role, or change uid, owner, Space, credentials, or routes; ask a human document admin to perform the deletion. Do not claim success, even if the document was already deleted.

Backends differ in their raw error shape. The CLI normalizes both:

• matters (structured): {error:{code, message, details}} → passes through into detail unchanged.
• dmworkim (flat): {msg, status} → mapped to code/message via HTTP status.

4. Universal flags

These flags work on every command (they are root-level persistent flags):

Paginated operations additionally expose:

5. Error taxonomy and exit codes

Agents should switch on error.code first (specific, deterministic), then error.type (broad), then exit_code (coarse).

The hint field is a one-line next action meant for an agent: follow it literally where it applies. E.g. MATTER_NOT_FOUND → "verify ID with octo-cli matters list".

6. Input patterns

Promoted flags vs --data

Simple top-level body fields auto-promote to typed flags (strings, integers, booleans, []string). For objects, arrays-of-objects, or when sending a large payload, use --data:

bashCopy code
octo-cli thread create group-abc --name "design review"
octo-cli message send --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"hi"}}'
octo-cli message send --data @body.json
octo-cli some-cmd --data @-            # read JSON from stdin

Explicit flags override fields set in --data. The --data escape hatch exists on every non-multipart command.

Piping with --jq

bashCopy code
octo-cli group list --jq '.data[].id' | xargs -I{} octo-cli group get {}

Paginating

bashCopy code
octo-cli docs search --keyword "spec" --page-all --page-limit 20

--page-all applies to any list operation that reports a cursor in _pagination. The merged output drops _pagination — you get a flat data array.

Dry-run for agent self-verification

bashCopy code
octo-cli message send --data '{"channel_id":"chat-1","channel_type":1,"payload":{"type":1,"content":"foo"}}' --dry-run

Prints the exact HTTP request body and URL, emits no side effect.

7. Discovering the API

The registry is embedded in the binary — no network needed:

bashCopy code
octo-cli schema --list                # all services + operation IDs
octo-cli schema --list message        # operations in one domain
octo-cli schema message.send          # full request/response schema
octo-cli config show                  # resolved config (token masked)
octo-cli auth status                  # active bot identity (whoami)
octo-cli auth list                    # stored profiles (no tokens)

When an operation isn't auto-registered yet or you need low-level control:

bashCopy code
octo-cli api GET  /api/v1/messages --params '{"chat_id":"chat-1"}'
octo-cli api POST /api/v1/messages --data @body.json

8. Domain skills

Once these fundamentals are understood, load the skill for the domain you need:

• octo-matter — matters (todos/tasks), assignees, channels, timeline, AI extract — temporarily withheld (backend API stabilizing; not currently loadable)
• octo-messaging — message send/edit/sync/read-receipt, groups, threads, events
• octo-files — file upload/download, presigned credentials, bot housekeeping
• octo-docs — docs domain (CRDT/Yjs): documents, spreadsheets, whiteboard scenes, members/sharing, comments, versions, attachments
• octo-html — HTML docs domain (octo-doc, a DIFFERENT backend from octo-docs): self-contained interactive HTML documents, share codes, media assets, comments, agent element read/replace
• octo-summary — create owner-only summaries from explicit sources, then discover, read, and cite summaries visible to the personal Agent's human owner — temporarily withheld (create backend at Mininglamp-OSS/octo-smart-summary#181 not yet merged/deployed/enabled; not currently loadable)