Octo Docs

octo-docs — bot access to Octo documents, spreadsheets, whiteboards & presentations

This skill is progressive: this file covers the shared essentials (auth, document lifecycle) and routes you to a focused reference file for each surface. Load the one reference that matches your task — don't read them all. The reference files sit next to this file in the skill directory.

All commands call $OCTO_API_BASE_URL/v1/bot/docs/*.

For a named spreadsheet tab, use docs sheet list <docId> to discover IDs and names, then docs sheet get <docId> --sheet-id <sheetId> --limit 1000. See sheet.md for exact-name selection, scoped pagination and deployment checks.

When to read which reference

The first four split by doc_type (what kind of document you're handling); common.md covers shared document management; PPT comments, versions and media usage are described in ppt.md. Read a reference with your file tool (it sits beside this SKILL.md, e.g. sheet.md), or reprint the whole skill set anytime with octo-cli skills octo-docs.

Pick by doc_type: a doc body → doc.md; a sheet → sheet.md; a board → board.md; a PPT → ppt.md; an html result → the separate octo-html skill. Using the wrong surface returns 409 unsupported_doc_type. For an HTML search result, run docs get <docId> and use its octoDocSlug value as the document reference with html get <octoDocSlug> (or another html command). Do not retry HTML through docs content, docs sheet, or docs scene. docs get <docId> reports the doc_type, your role, and octoDocSlug for HTML. That value is the canonical doc_id for new documents and the retained legacy slug for old documents; callers do not infer the distinction from mount state.

Auth & space

• Authenticate with a bot token via a stored profile (--profile / --bot-id) or OCTO_BOT_TOKEN; both app_* and bf_* tokens work. Confirm with octo-cli config show.
• Do not pass a space flag for docs. The bot mount resolves the space server-side from the token and deliberately ignores any client-supplied space header (anti-spoof). Role enforcement (reader / writer / admin) also happens server-side, so the CLI surfaces the backend's 403/404 envelopes unchanged.

Document lifecycle

Bots cannot delete documents, even as owner/admin or for cleanup of their own test documents. Do not run octo-cli docs delete <docId>. Ask a human with document admin permission to delete the document in Octo.

The docs-backend bot-deletion policy returns HTTP 403 / bot_delete_forbidden for both DELETE /v1/bot/docs/:docId and DELETE /v1/bot/docs/octo-doc/:octoDocSlug, including already-deleted retries. The CLI emits error.type: permission and keeps that error code. Stop on this denial: do not retry or treat it as successful cleanup. Identity comes from server-side authentication; changing uid, owner, Space, or the bot's role does not authorize deletion. Do not switch to html rm, a raw API call, another credential, or an older deployment to work around the policy.

Bot creation and editing remain available under their existing permissions. Deleting a comment/version, sheet rows/columns, or individual scene elements is not whole-document deletion and retains its own permission checks.

bashCopy code
# Create an empty doc (caller becomes owner/admin). A new doc has NO body —
# seed a `doc` with `docs content edit` (doc.md), a `sheet` with
# `docs sheet edit` (sheet.md), and a `board` with `docs scene edit` (board.md).
octo-cli docs create [--title "Runbook"] [--folderId f_123] [--docType doc|sheet|board]

# Create a presentation from a template (ppt.md).
octo-cli docs create --docType html_ppt --title "Quarterly Review" --templateId signal --idempotency-key <unique-key>
# Native gallery choices: signal, terra, orbital, picnic (requires the matching backend).
# Read ppt.md for style selection and the create -> read -> edit -> verify workflow.

# List docs you own or are a member of. Page-based (see the pagination note below).
octo-cli docs list [--folderId f_123] [--page 1] [--pageSize 20] [--sort updatedAt:desc]

# Full-text search every doc the bot may read. Repeat --doc-type to combine kinds.
# Search is cursor-based; --page-all follows nextCursor automatically.
octo-cli docs search --keyword "quarterly plan" [--doc-type doc|sheet|board|html] [--page-size 20] [--page-all]

octo-cli docs get    <docId>                 # metadata + doc_type + your role

# Import a local file into an existing target. .md/.markdown/.docx require a doc;
# .xlsx requires a sheet and imports its first visible worksheet.
octo-cli docs import <docId> --file ./input.md

# Export to a local file. -o is required and its extension must match.
# --export-format is distinct from global --format (the envelope renderer).
octo-cli docs export <docId> --export-format pdf -o ./output.pdf
# Other accepted matching pairs: md/.md, docx/.docx, xlsx/.xlsx, png/.png, svg/.svg

octo-cli docs rename <docId> --title "New title"

Pagination note

Pagination depends on the endpoint's response contract:

• docs list is page-based — response is {total, items}. Walk it with --page / --pageSize; --page-all is not offered.
• docs search is cursor-based — response is {total, items, nextCursor}. Pass nextCursor back via --cursor, or use --page-all to follow it automatically; --page-limit caps automatic requests (default 10).
• docs comments list and docs versions list are cursor-based — response is {items, nextCursor}. Pass the returned nextCursor back via --cursor to get the next page; stop when nextCursor is null.

Not in this version

docs attachments upload (binary helper), invites, access-requests, and link-card are out of scope here. Body editing is limited to doc_type: doc incremental block ops (doc.md), the spreadsheet batches documented in sheet.md, doc_type: board scene batches (board.md), and revision-checked PPT edits (ppt.md). doc_type: html belongs to the separate html domain, uses its returned document reference, and is published as immutable versions; it cannot be read or edited through these content surfaces. The document outline is not editable through the CLI.

Schema lookup

Any operation's parameters + response schema come from the embedded registry:

bashCopy code
octo-cli schema docs.create
octo-cli schema docs.search
octo-cli schema docs.content.edit     # + docs.sheet.edit / docs.sheet.replace / docs.sheet.rows.insert / docs.sheet.columns.delete / …