octo-files

octo-files — file I/O and bot housekeeping

Two small domains are covered here because they share a base URL ($OCTO_API_BASE_URL/v1/bot/*) and are usually needed together:

• file — 4 ops, no bot-kind restrictions
• bot — 6 ops, no bot-kind restrictions

1. File operations

octo-cli file upload      --file ./report.pdf [--type chat] [--path subdir/]
octo-cli file download    <path> --format json > saved.bin      # <path> = storage key (no bucket prefix), see note below
octo-cli file credentials --filename report.pdf
octo-cli file presigned   --filename report.pdf --fileSize 1048576   # --fileSize (bytes) is REQUIRED

upload — multipart form

Unlike every other command, file upload sends a multipart multipart/form-data body, not JSON. The --file flag is required and names a local path; --type (default chat) and --path become form text fields. Promoted body flags declared in the spec go in as text fields alongside the binary.

The response envelope carries the returned file descriptor under data — use it to build attachment references in message send.

download — returns a presigned URL

file download <path> issues a GET. The backend responds with a 302 redirect to the storage tier. The CLI does not stream raw bytes — instead it returns a JSON envelope containing the presigned URL:

octo-cli file download /chat/2026/05/abc123.png
# → {"ok":true,"data":{"url":"https://s3.../abc123.png?...","status":302,"content_type":"image/png"}}

To actually fetch the file, use the URL from the response:

octo-cli file download /chat/2026/05/abc123.png --jq '.data.url' | xargs curl -o out.png

Direct-to-S3 uploads

For files too large for multipart, ask the backend for a presigned target and upload directly:

size=$(stat -f%z big.zip 2>/dev/null || stat -c%s big.zip)    # fileSize in bytes (REQUIRED; no padding)
cred=$(octo-cli file presigned --filename big.zip --fileSize "$size")
url=$(jq   -r '.data.uploadUrl'                   <<<"$cred")
ctype=$(jq -r '.data.contentType'                 <<<"$cred")
cdisp=$(jq -r '.data.contentDisposition // empty' <<<"$cred")
curl -X PUT -T big.zip -H "Content-Type: $ctype" ${cdisp:+-H "Content-Disposition: $cdisp"} "$url"