feat: add --fields and --max-lines global CLI options (DIS-145)

Add --fields <fields> to select specific JSON fields in output.
Add --max-lines <lines> to truncate output with line count indicator.

Uses Commander preAction hook and module-level output options to avoid
changing any command files. Field filtering handles plain objects,
arrays, and wrapped API responses (e.g. {nfts: [...], next: ...}).
Truncation appends '... (N more lines)' indicator.

Co-Authored-By: Chris K <ckorhonen@gmail.com>

Author: devin-ai-integration[bot]

src/cli.ts

@@ -11,7 +11,7 @@ import {
   swapsCommand,
   tokensCommand,
 } from "./commands/index.js"
-import type { OutputFormat } from "./output.js"
+import { type OutputFormat, setOutputOptions } from "./output.js"
 import { parseIntOption } from "./parse.js"
 
 const BANNER = `
@@ -38,6 +38,11 @@ program
   .option("--base-url <url>", "API base URL")
   .option("--timeout <ms>", "Request timeout in milliseconds", "30000")
   .option("--verbose", "Log request and response info to stderr")
+  .option(
+    "--fields <fields>",
+    "Comma-separated list of fields to include in output",
+  )
+  .option("--max-lines <lines>", "Truncate output after N lines")
 
 function getClient(): OpenSeaClient {
   const opts = program.opts<{
@@ -72,6 +77,19 @@ function getFormat(): OutputFormat {
   return "json"
 }
 
+program.hook("preAction", () => {
+  const opts = program.opts<{
+    fields?: string
+    maxLines?: string
+  }>()
+  setOutputOptions({
+    fields: opts.fields?.split(",").map(f => f.trim()),
+    maxLines: opts.maxLines
+      ? parseIntOption(opts.maxLines, "--max-lines")
+      : undefined,
+  })
+})
+
 program.addCommand(collectionsCommand(getClient, getFormat))
 program.addCommand(nftsCommand(getClient, getFormat))
 program.addCommand(listingsCommand(getClient, getFormat))

src/index.ts

@@ -1,6 +1,6 @@
 export { OpenSeaAPIError, OpenSeaClient } from "./client.js"
-export type { OutputFormat } from "./output.js"
-export { formatOutput } from "./output.js"
+export type { OutputFormat, OutputOptions } from "./output.js"
+export { formatOutput, setOutputOptions } from "./output.js"
 export { OpenSeaCLI } from "./sdk.js"
 export { formatToon } from "./toon.js"
 export type * from "./types/index.js"

src/output.ts

@@ -2,14 +2,36 @@ import { formatToon } from "./toon.js"
 
 export type OutputFormat = "json" | "table" | "toon"
 
+export interface OutputOptions {
+  fields?: string[]
+  maxLines?: number
+}
+
+let _outputOptions: OutputOptions = {}
+
+export function setOutputOptions(options: OutputOptions): void {
+  _outputOptions = options
+}
+
 export function formatOutput(data: unknown, format: OutputFormat): string {
+  const processed = _outputOptions.fields
+    ? filterFields(data, _outputOptions.fields)
+    : data
+
+  let result: string
   if (format === "table") {
-    return formatTable(data)
+    result = formatTable(processed)
+  } else if (format === "toon") {
+    result = formatToon(processed)
+  } else {
+    result = JSON.stringify(processed, null, 2)
   }
-  if (format === "toon") {
-    return formatToon(data)
+
+  if (_outputOptions.maxLines) {
+    result = truncateOutput(result, _outputOptions.maxLines)
   }
-  return JSON.stringify(data, null, 2)
+
+  return result
 }
 
 function formatTable(data: unknown): string {
@@ -57,3 +79,51 @@ function formatTable(data: unknown): string {
 
   return String(data)
 }
+
+function pickFields(
+  obj: Record<string, unknown>,
+  fields: string[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const field of fields) {
+    if (field in obj) {
+      result[field] = obj[field]
+    }
+  }
+  return result
+}
+
+function filterFields(data: unknown, fields: string[]): unknown {
+  if (Array.isArray(data)) {
+    return data.map(item => filterFields(item, fields))
+  }
+  if (data && typeof data === "object") {
+    const obj = data as Record<string, unknown>
+    const arrayKeys = Object.keys(obj).filter(k => Array.isArray(obj[k]))
+    if (arrayKeys.length > 0) {
+      const result: Record<string, unknown> = {}
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = Array.isArray(value)
+          ? value.map(item =>
+              item && typeof item === "object"
+                ? pickFields(item as Record<string, unknown>, fields)
+                : item,
+            )
+          : value
+      }
+      return result
+    }
+    return pickFields(obj, fields)
+  }
+  return data
+}
+
+function truncateOutput(text: string, maxLines: number): string {
+  const lines = text.split("\n")
+  if (lines.length <= maxLines) return text
+  const omitted = lines.length - maxLines
+  return (
+    lines.slice(0, maxLines).join("\n") +
+    `\n... (${omitted} more line${omitted === 1 ? "" : "s"})`
+  )
+}

test/output.test.ts

@@ -1,7 +1,11 @@
-import { describe, expect, it } from "vitest"
-import { formatOutput } from "../src/output.js"
+import { afterEach, describe, expect, it } from "vitest"
+import { formatOutput, setOutputOptions } from "../src/output.js"
 
 describe("formatOutput", () => {
+  afterEach(() => {
+    setOutputOptions({})
+  })
+
   describe("json format", () => {
     it("formats data as pretty JSON", () => {
       const data = { name: "test", value: 42 }
@@ -70,4 +74,134 @@ describe("formatOutput", () => {
       expect(formatOutput(42, "table")).toBe("42")
     })
   })
+
+  describe("--fields option", () => {
+    it("filters top-level fields on a plain object", () => {
+      setOutputOptions({ fields: ["name", "collection"] })
+      const data = {
+        name: "Cool NFT",
+        collection: "cool-cats",
+        description: "A cool cat",
+        image_url: "https://example.com/img.png",
+      }
+      const result = JSON.parse(formatOutput(data, "json"))
+      expect(result).toEqual({ name: "Cool NFT", collection: "cool-cats" })
+    })
+
+    it("filters fields on items inside wrapped arrays", () => {
+      setOutputOptions({ fields: ["identifier", "name"] })
+      const data = {
+        nfts: [
+          {
+            identifier: "1",
+            name: "NFT #1",
+            image_url: "https://example.com/1.png",
+          },
+          {
+            identifier: "2",
+            name: "NFT #2",
+            image_url: "https://example.com/2.png",
+          },
+        ],
+        next: "cursor123",
+      }
+      const result = JSON.parse(formatOutput(data, "json"))
+      expect(result).toEqual({
+        nfts: [
+          { identifier: "1", name: "NFT #1" },
+          { identifier: "2", name: "NFT #2" },
+        ],
+        next: "cursor123",
+      })
+    })
+
+    it("filters fields on a bare array", () => {
+      setOutputOptions({ fields: ["name"] })
+      const data = [
+        { name: "Alice", age: 30 },
+        { name: "Bob", age: 25 },
+      ]
+      const result = JSON.parse(formatOutput(data, "json"))
+      expect(result).toEqual([{ name: "Alice" }, { name: "Bob" }])
+    })
+
+    it("ignores fields that do not exist", () => {
+      setOutputOptions({ fields: ["name", "nonexistent"] })
+      const data = { name: "test", value: 42 }
+      const result = JSON.parse(formatOutput(data, "json"))
+      expect(result).toEqual({ name: "test" })
+    })
+
+    it("returns primitives unchanged", () => {
+      setOutputOptions({ fields: ["name"] })
+      expect(formatOutput("hello", "json")).toBe('"hello"')
+    })
+
+    it("works with table format", () => {
+      setOutputOptions({ fields: ["name"] })
+      const data = [
+        { name: "Alice", age: 30 },
+        { name: "Bob", age: 25 },
+      ]
+      const result = formatOutput(data, "table")
+      expect(result).toContain("name")
+      expect(result).not.toContain("age")
+    })
+  })
+
+  describe("--max-lines option", () => {
+    it("truncates output exceeding max lines", () => {
+      setOutputOptions({ maxLines: 3 })
+      const data = { a: 1, b: 2, c: 3, d: 4, e: 5 }
+      const result = formatOutput(data, "json")
+      const lines = result.split("\n")
+      expect(lines).toHaveLength(4)
+      expect(lines[3]).toBe("... (4 more lines)")
+    })
+
+    it("does not truncate when output fits within max lines", () => {
+      setOutputOptions({ maxLines: 100 })
+      const data = { a: 1 }
+      const result = formatOutput(data, "json")
+      expect(result).not.toContain("...")
+      expect(result).toBe(JSON.stringify(data, null, 2))
+    })
+
+    it("uses singular 'line' for exactly one omitted line", () => {
+      setOutputOptions({ maxLines: 2 })
+      const data = { a: 1 }
+      const result = formatOutput(data, "json")
+      const lines = result.split("\n")
+      expect(lines[lines.length - 1]).toBe("... (1 more line)")
+    })
+
+    it("works with table format", () => {
+      setOutputOptions({ maxLines: 2 })
+      const data = [{ name: "Alice" }, { name: "Bob" }, { name: "Charlie" }]
+      const result = formatOutput(data, "table")
+      const lines = result.split("\n")
+      expect(lines).toHaveLength(3)
+      expect(lines[2]).toMatch(/\.\.\. \(\d+ more lines?\)/)
+    })
+  })
+
+  describe("--fields and --max-lines combined", () => {
+    it("applies field filtering then truncation", () => {
+      setOutputOptions({ fields: ["name"], maxLines: 3 })
+      const data = {
+        nfts: [
+          { name: "A", id: 1 },
+          { name: "B", id: 2 },
+          { name: "C", id: 3 },
+          { name: "D", id: 4 },
+        ],
+        next: "cursor",
+      }
+      const result = formatOutput(data, "json")
+      expect(result).not.toContain("id")
+      const lines = result.split("\n")
+      expect(lines).toHaveLength(4)
+      expect(lines[3]).toMatch(/\.\.\. \(\d+ more lines?\)/)
+    })
+  })
 })