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:

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

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:

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:

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

{
  "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:

{
  "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.