feat: support binary file downloads with --output flag

[siddharth-bhansali]

Summary

Adds support for binary (non-JSON) responses from the API passthrough layer, fixing a crash that occurred when downloading files from Google Drive and other platforms that return binary data.

The Problem

When using actions that return binary data (e.g., Google Drive Get File with alt=media, or Export for native Google Docs), the CLI crashed with:

Error: Unexpected token '%', "%PDF-1.4\n%"... is not valid JSON

This happened because executePassthroughRequest unconditionally called JSON.parse() on the response body, which fails for binary content like PDFs, images, and documents.

This blocked a very common workflow — downloading document files from Google Drive for local processing by AI agents.

The Fix

Binary response detection (src/lib/api.ts)

• After receiving a response, check the Content-Type header
• If the response is not application/json or text/*, treat it as binary
• Without --output: return metadata (size, contentType, and a message prompting the user to use --output)
• With --output <path>: save the raw binary data to the specified file path

New --output flag (src/index.ts, src/commands/actions.ts, src/lib/types.ts)

• Added --output <path> option to one actions execute
• Passes through to the API layer for binary file saving

Usage

# Download a PDF from Google Drive
one actions execute google-drive <get-file-action> <key> \
  --path-vars '{"fileId": "abc123"}' \
  --query-params '{"alt": "media"}' \
  --output ./file.pdf

# Export a native Google Doc as PDF
one actions execute google-drive <export-action> <key> \
  --path-vars '{"fileId": "abc123"}' \
  --query-params '{"mimeType": "application/pdf"}' \
  --output ./export.pdf

# Without --output, returns metadata instead of crashing
one actions execute google-drive <get-file-action> <key> \
  --path-vars '{"fileId": "abc123"}' \
  --query-params '{"alt": "media"}'
# → {"binary": true, "size": 415272, "contentType": "application/octet-stream", "message": "..."}

Verified

Test	Before	After
alt=media without --output	Crash: not valid JSON	Returns metadata (size, contentType)
alt=media with --output	N/A	Saves valid PDF to disk (415KB, %PDF-1.4 header)
Export Google Doc as PDF	Crash: not valid JSON	Saves valid PDF to disk (24KB)
Export uploaded .pdf	403: Export only supports Docs Editors files	Same (expected — Google API limitation)
Normal JSON responses	Works	Unchanged — no regression

Files Changed

• src/lib/api.ts — Binary response detection and file saving logic
• src/lib/types.ts — Added output to ExecuteActionArgs
• src/commands/actions.ts — Pass output option through to API
• src/index.ts — Register --output CLI option

Closes withoneai/knowledge#46

[linear]

INT-2111