feat: make download path optional with stdout support

- Change `object download <id> <path>` to `object download <id> [path]`
- When path is omitted, auto-resolve using object name/content_type
  via the new getDefaultDownloadPath utility
- When path is `-`, write downloaded data to stdout
- Warn on stderr when writing binary content types to a TTY
- Structured output (-o json) goes to stderr when using stdout mode

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jason-rl

src/commands/object/download.ts

@@ -5,18 +5,46 @@
 import { writeFile } from "fs/promises";
 import { getClient } from "../../utils/client.js";
 import { output, outputError } from "../../utils/output.js";
+import { getDefaultDownloadPath } from "../../utils/downloadPath.js";
+import { processUtils } from "../../utils/processUtils.js";
 
 interface DownloadObjectOptions {
   id: string;
-  path: string;
+  path?: string;
   extract?: boolean;
   durationSeconds?: number;
   output?: string;
 }
 
+/** Content types that produce non-text (binary) output */
+const BINARY_CONTENT_TYPES = new Set([
+  "binary",
+  "gzip",
+  "tar",
+  "tgz",
+  "unspecified",
+]);
+
 export async function downloadObject(options: DownloadObjectOptions) {
   try {
     const client = getClient();
+    const isStdout = options.path === "-";
+
+    // Resolve the download path when not provided or when writing to stdout
+    // (stdout mode still needs content_type for the TTY binary warning)
+    let resolvedPath = options.path;
+    let contentType: string | undefined;
+    if (!resolvedPath || isStdout) {
+      const obj = await client.objects.retrieve(options.id);
+      contentType = obj.content_type;
+      if (!resolvedPath) {
+        resolvedPath = getDefaultDownloadPath(
+          obj.name,
+          obj.id,
+          obj.content_type,
+        );
+      }
+    }
 
     // Get the download URL
     const downloadUrlResponse = await client.objects.download(options.id, {
@@ -32,19 +60,40 @@ export async function downloadObject(options: DownloadObjectOptions) {
     // Save the file
     const arrayBuffer = await response.arrayBuffer();
     const buffer = Buffer.from(arrayBuffer);
-    await writeFile(options.path, buffer);
+
+    if (isStdout) {
+      // Warn if writing binary data to a terminal
+      if (
+        processUtils.stdout.isTTY &&
+        contentType &&
+        BINARY_CONTENT_TYPES.has(contentType)
+      ) {
+        processUtils.stderr.write(
+          "Warning: writing binary data to terminal; pipe to a file or command instead\n",
+        );
+      }
+      // Raw process.stdout for binary data (processUtils.stdout.write only accepts string)
+      process.stdout.write(buffer);
+    } else {
+      await writeFile(resolvedPath, buffer);
+    }
 
     // TODO: Handle extraction if requested (options.extract)
 
     const result = {
       id: options.id,
-      path: options.path,
+      path: isStdout ? "-" : resolvedPath,
       extracted: options.extract || false,
     };
 
-    // Default: just output the local path for easy scripting
-    if (!options.output || options.output === "text") {
-      console.log(options.path);
+    if (isStdout) {
+      // Structured output goes to stderr to avoid mixing with data (always JSON)
+      if (options.output && options.output !== "text") {
+        processUtils.stderr.write(JSON.stringify(result, null, 2) + "\n");
+      }
+    } else if (!options.output || options.output === "text") {
+      // Default: just output the local path for easy scripting
+      console.log(resolvedPath);
     } else {
       output(result, { format: options.output, defaultFormat: "json" });
     }

src/utils/commands.ts

@@ -630,8 +630,10 @@ export function createProgram(): Command {
     });
 
   object
-    .command("download <id> <path>")
-    .description("Download object to local file")
+    .command("download <id> [path]")
+    .description(
+      "Download object to local file (path defaults to ./<name> with inferred extension; use - for stdout)",
+    )
     .option("--extract", "Extract downloaded archive after download")
     .option(
       "--duration-seconds <seconds>",