@open-pencil/cli 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-pencil/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@open-pencil/core": "^0.9.0",
+    "@open-pencil/core": "^0.11.0",
     "agentfmt": "^0.1.3",
     "canvaskit-wasm": "^0.40.0",
     "citty": "^0.1.6"

package/src/app-client.ts

@@ -11,14 +11,14 @@ export async function getAppToken(): Promise<string> {
   if (!res || !res.ok) {
     throw new Error(
       `Could not connect to OpenPencil app on localhost:${AUTOMATION_HTTP_PORT}.\n` +
-      'Is the app running? Start it with: bun run tauri dev'
+        'Is the app running? Start it with: bun run tauri dev'
     )
   }
   const data = (await res.json()) as { status: string; token?: string }
   if (data.status !== 'ok' || !data.token) {
     throw new Error(
       'OpenPencil app is running but no document is open.\n' +
-      'Open a document in the app, or provide a .fig file path.'
+        'Open a document in the app, or provide a .fig file path.'
     )
   }
   cachedToken = data.token
@@ -37,7 +37,10 @@ export async function rpc<T = unknown>(command: string, args: unknown = {}): Pro
   })
 
   if (!res.ok) {
-    const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` }))) as { error?: string; ok?: boolean }
+    const body = (await res.json().catch(() => ({ error: `HTTP ${res.status}` }))) as {
+      error?: string
+      ok?: boolean
+    }
     throw new Error(body.error ?? `RPC failed: HTTP ${res.status}`)
   }
 

package/src/commands/analyze/clusters.ts

@@ -1,27 +1,13 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../../headless'
+import { executeRpcCommand, calcClusterConfidence } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../../app-client'
 import { bold, fmtList, fmtSummary } from '../../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../../headless'
 
 import type { AnalyzeClustersResult } from '@open-pencil/core'
 
-function calcConfidence(nodes: Array<{ width: number; height: number; childCount: number }>): number {
-  if (nodes.length < 2) return 100
-  const base = nodes[0]
-  let score = 0
-  for (const node of nodes.slice(1)) {
-    const sizeDiff = Math.abs(node.width - base.width) + Math.abs(node.height - base.height)
-    const childDiff = Math.abs(node.childCount - base.childCount)
-    if (sizeDiff <= 4 && childDiff === 0) score++
-    else if (sizeDiff <= 10 && childDiff <= 1) score += 0.8
-    else if (sizeDiff <= 20 && childDiff <= 2) score += 0.6
-    else score += 0.4
-  }
-  return Math.round((score / (nodes.length - 1)) * 100)
-}
-
 function formatSignature(sig: string): string {
   const [typeSize, children] = sig.split('|')
   const type = typeSize.split(':')[0]
@@ -39,8 +25,15 @@ function formatSignature(sig: string): string {
   return `${typeName} > [${childParts.join(', ')}]`
 }
 
-async function getData(file: string | undefined, args: { limit?: string; 'min-size'?: string; 'min-count'?: string }): Promise<AnalyzeClustersResult> {
-  const rpcArgs = { limit: Number(args.limit ?? 20), minSize: Number(args['min-size'] ?? 30), minCount: Number(args['min-count'] ?? 2) }
+async function getData(
+  file: string | undefined,
+  args: { limit?: string; 'min-size'?: string; 'min-count'?: string }
+): Promise<AnalyzeClustersResult> {
+  const rpcArgs = {
+    limit: Number(args.limit ?? 20),
+    minSize: Number(args['min-size'] ?? 30),
+    minCount: Number(args['min-count'] ?? 2)
+  }
   if (isAppMode(file)) return rpc<AnalyzeClustersResult>('analyze_clusters', rpcArgs)
   const graph = await loadDocument(requireFile(file))
   return executeRpcCommand(graph, 'analyze_clusters', rpcArgs) as AnalyzeClustersResult
@@ -49,7 +42,11 @@ async function getData(file: string | undefined, args: { limit?: string; 'min-si
 export default defineCommand({
   meta: { description: 'Find repeated design patterns (potential components)' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: '.fig file path (omit to connect to running app)',
+      required: false
+    },
     limit: { type: 'string', description: 'Max clusters to show', default: '20' },
     'min-size': { type: 'string', description: 'Min node size in px', default: '30' },
     'min-count': { type: 'string', description: 'Min instances to form cluster', default: '2' },
@@ -74,7 +71,7 @@ export default defineCommand({
 
     const items = data.clusters.map((c) => {
       const first = c.nodes[0]
-      const confidence = calcConfidence(c.nodes)
+      const confidence = calcClusterConfidence(c.nodes)
 
       const widths = c.nodes.map((n) => n.width)
       const heights = c.nodes.map((n) => n.height)
@@ -93,7 +90,10 @@ export default defineCommand({
         details: {
           size: sizeStr,
           structure: formatSignature(c.signature),
-          examples: c.nodes.slice(0, 3).map((n) => n.id).join(', ')
+          examples: c.nodes
+            .slice(0, 3)
+            .map((n) => n.id)
+            .join(', ')
         }
       }
     })
@@ -102,11 +102,13 @@ export default defineCommand({
 
     const clusteredNodes = data.clusters.reduce((sum, c) => sum + c.nodes.length, 0)
     console.log('')
-    console.log(fmtSummary({
-      clusters: data.clusters.length,
-      'total nodes': data.totalNodes,
-      clustered: clusteredNodes
-    }))
+    console.log(
+      fmtSummary({
+        clusters: data.clusters.length,
+        'total nodes': data.totalNodes,
+        clustered: clusteredNodes
+      })
+    )
     console.log('')
   }
 })

package/src/commands/analyze/colors.ts

@@ -1,13 +1,17 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../../app-client'
 import { bold, fmtHistogram, fmtList, fmtSummary } from '../../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../../headless'
 
 import type { AnalyzeColorsResult } from '@open-pencil/core'
 
-async function getData(file: string | undefined, args: { threshold?: string; similar?: boolean }): Promise<AnalyzeColorsResult> {
+async function getData(
+  file: string | undefined,
+  args: { threshold?: string; similar?: boolean }
+): Promise<AnalyzeColorsResult> {
   const rpcArgs = { threshold: Number(args.threshold ?? 15), similar: args.similar }
   if (isAppMode(file)) return rpc<AnalyzeColorsResult>('analyze_colors', rpcArgs)
   const graph = await loadDocument(requireFile(file))
@@ -17,9 +21,17 @@ async function getData(file: string | undefined, args: { threshold?: string; sim
 export default defineCommand({
   meta: { description: 'Analyze color palette usage' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: '.fig file path (omit to connect to running app)',
+      required: false
+    },
     limit: { type: 'string', description: 'Max colors to show', default: '30' },
-    threshold: { type: 'string', description: 'Distance threshold for clustering similar colors (0–50)', default: '15' },
+    threshold: {
+      type: 'string',
+      description: 'Distance threshold for clustering similar colors (0–50)',
+      default: '15'
+    },
     similar: { type: 'boolean', description: 'Show similar color clusters' },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
@@ -57,7 +69,11 @@ export default defineCommand({
 
     console.log('')
     console.log(
-      fmtSummary({ 'unique colors': data.colors.length, 'from variables': fromVars.length, hardcoded: hardcoded.length })
+      fmtSummary({
+        'unique colors': data.colors.length,
+        'from variables': fromVars.length,
+        hardcoded: hardcoded.length
+      })
     )
 
     if (args.similar && data.clusters.length > 0) {

package/src/commands/analyze/index.ts

@@ -1,9 +1,9 @@
 import { defineCommand } from 'citty'
 
+import clusters from './clusters'
 import colors from './colors'
-import typography from './typography'
 import spacing from './spacing'
-import clusters from './clusters'
+import typography from './typography'
 
 export default defineCommand({
   meta: { description: 'Analyze design tokens and patterns' },

package/src/commands/analyze/spacing.ts

@@ -1,9 +1,10 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../../app-client'
 import { bold, kv, fmtHistogram, fmtSummary } from '../../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../../headless'
 
 import type { AnalyzeSpacingResult } from '@open-pencil/core'
 
@@ -16,7 +17,11 @@ async function getData(file?: string): Promise<AnalyzeSpacingResult> {
 export default defineCommand({
   meta: { description: 'Analyze spacing values (gap, padding)' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: '.fig file path (omit to connect to running app)',
+      required: false
+    },
     grid: { type: 'string', description: 'Base grid size to check against', default: '8' },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
@@ -67,7 +72,9 @@ export default defineCommand({
       return
     }
 
-    console.log(fmtSummary({ 'gap values': data.gaps.length, 'padding values': data.paddings.length }))
+    console.log(
+      fmtSummary({ 'gap values': data.gaps.length, 'padding values': data.paddings.length })
+    )
 
     const offGridGaps = data.gaps.filter((g) => g.value % gridSize !== 0)
     const offGridPaddings = data.paddings.filter((p) => p.value % gridSize !== 0)

package/src/commands/analyze/typography.ts

@@ -1,9 +1,10 @@
 import { defineCommand } from 'citty'
 
-import { loadDocument } from '../../headless'
+import { executeRpcCommand } from '@open-pencil/core'
+
 import { isAppMode, requireFile, rpc } from '../../app-client'
 import { bold, fmtHistogram, fmtSummary } from '../../format'
-import { executeRpcCommand } from '@open-pencil/core'
+import { loadDocument } from '../../headless'
 
 import type { AnalyzeTypographyResult } from '@open-pencil/core'
 
@@ -28,8 +29,15 @@ async function getData(file?: string): Promise<AnalyzeTypographyResult> {
 export default defineCommand({
   meta: { description: 'Analyze typography usage' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
-    'group-by': { type: 'string', description: 'Group by: family, size, weight (default: show all styles)' },
+    file: {
+      type: 'positional',
+      description: '.fig file path (omit to connect to running app)',
+      required: false
+    },
+    'group-by': {
+      type: 'string',
+      description: 'Group by: family, size, weight (default: show all styles)'
+    },
     limit: { type: 'string', description: 'Max styles to show', default: '30' },
     json: { type: 'boolean', description: 'Output as JSON' }
   },
@@ -57,7 +65,9 @@ export default defineCommand({
       console.log('')
       console.log(
         fmtHistogram(
-          [...byFamily.entries()].sort((a, b) => b[1] - a[1]).map(([family, count]) => ({ label: family, value: count }))
+          [...byFamily.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([family, count]) => ({ label: family, value: count }))
         )
       )
     } else if (groupBy === 'size') {
@@ -67,7 +77,9 @@ export default defineCommand({
       console.log('')
       console.log(
         fmtHistogram(
-          [...bySize.entries()].sort((a, b) => a[0] - b[0]).map(([size, count]) => ({ label: `${size}px`, value: count }))
+          [...bySize.entries()]
+            .sort((a, b) => a[0] - b[0])
+            .map(([size, count]) => ({ label: `${size}px`, value: count }))
         )
       )
     } else if (groupBy === 'weight') {
@@ -77,7 +89,9 @@ export default defineCommand({
       console.log('')
       console.log(
         fmtHistogram(
-          [...byWeight.entries()].sort((a, b) => b[1] - a[1]).map(([weight, count]) => ({ label: `${weight} ${weightName(weight)}`, value: count }))
+          [...byWeight.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([weight, count]) => ({ label: `${weight} ${weightName(weight)}`, value: count }))
         )
       )
     } else {
@@ -91,7 +105,9 @@ export default defineCommand({
     }
 
     console.log('')
-    console.log(fmtSummary({ 'unique styles': data.styles.length, 'text nodes': data.totalTextNodes }))
+    console.log(
+      fmtSummary({ 'unique styles': data.styles.length, 'text nodes': data.totalTextNodes })
+    )
     console.log('')
   }
 })

package/src/commands/convert.ts

@@ -0,0 +1,56 @@
+import { basename, extname, resolve } from 'node:path'
+
+import { defineCommand } from 'citty'
+
+import { BUILTIN_IO_FORMATS, IORegistry } from '@open-pencil/core'
+
+import { requireFile } from '../app-client'
+import { ok, printError } from '../format'
+import { loadDocument } from '../headless'
+
+const io = new IORegistry(BUILTIN_IO_FORMATS)
+const WRITABLE_FORMATS = ['FIG'] as const
+
+type WritableFormat = (typeof WRITABLE_FORMATS)[number]
+
+function defaultOutput(file: string, format: WritableFormat): string {
+  const base = basename(file, extname(file))
+  return resolve(`${base}.${format.toLowerCase()}`)
+}
+
+export default defineCommand({
+  meta: { description: 'Convert a document to another writable format' },
+  args: {
+    file: {
+      type: 'positional',
+      description: 'Input document file path',
+      required: true
+    },
+    output: {
+      type: 'string',
+      alias: 'o',
+      description: 'Output file path (default: <name>.<format>)',
+      required: false
+    },
+    format: {
+      type: 'string',
+      alias: 'f',
+      description: 'Output format: fig (default: fig)',
+      default: 'fig'
+    }
+  },
+  async run({ args }) {
+    const format = args.format.toUpperCase() as WritableFormat
+    if (!WRITABLE_FORMATS.includes(format)) {
+      printError(`Invalid format "${args.format}". Use fig.`)
+      process.exit(1)
+    }
+
+    const file = requireFile(args.file)
+    const graph = await loadDocument(file)
+    const result = await io.writeDocument(format.toLowerCase(), graph)
+    const output = args.output ? resolve(args.output) : defaultOutput(file, format)
+    await Bun.write(output, result.data as Uint8Array)
+    console.log(ok(`Converted ${file} → ${output}`))
+  }
+})

package/src/commands/eval.ts

@@ -2,9 +2,9 @@ import { defineCommand } from 'citty'
 
 import { FigmaAPI } from '@open-pencil/core'
 
-import { loadDocument } from '../headless'
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { printError } from '../format'
+import { loadDocument } from '../headless'
 
 function printResult(value: unknown, json: boolean) {
   if (json || !process.stdout.isTTY) {
@@ -26,13 +26,22 @@ function serializeResult(value: unknown): unknown {
 export default defineCommand({
   meta: { description: 'Execute JavaScript with Figma plugin API' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
     code: { type: 'string', alias: 'c', description: 'JavaScript code to execute' },
     stdin: { type: 'boolean', description: 'Read code from stdin' },
     write: { type: 'boolean', alias: 'w', description: 'Write changes back to the input file' },
-    output: { type: 'string', alias: 'o', description: 'Write to a different file', required: false },
+    output: {
+      type: 'string',
+      alias: 'o',
+      description: 'Write to a different file',
+      required: false
+    },
     json: { type: 'boolean', description: 'Output as JSON' },
-    quiet: { type: 'boolean', alias: 'q', description: 'Suppress output' },
+    quiet: { type: 'boolean', alias: 'q', description: 'Suppress output' }
   },
   async run({ args }) {
     let code = args.code
@@ -80,13 +89,14 @@ export default defineCommand({
     }
 
     if (args.write || args.output) {
-      const { exportFigFile } = await import('@open-pencil/core')
+      const { BUILTIN_IO_FORMATS, IORegistry } = await import('@open-pencil/core')
+      const io = new IORegistry(BUILTIN_IO_FORMATS)
       const outPath = args.output ? args.output : file
-      const data = await exportFigFile(graph)
-      await Bun.write(outPath, new Uint8Array(data))
+      const result = await io.writeDocument('fig', graph)
+      await Bun.write(outPath, result.data as Uint8Array)
       if (!args.quiet) {
         console.error(`Written to ${outPath}`)
       }
     }
-  },
+  }
 })

package/src/commands/export.ts

@@ -1,15 +1,18 @@
-import { defineCommand } from 'citty'
 import { basename, extname, resolve } from 'node:path'
 
-import { renderNodesToSVG, sceneNodeToJSX, selectionToJSX } from '@open-pencil/core'
+import { defineCommand } from 'citty'
+
+import { BUILTIN_IO_FORMATS, IORegistry } from '@open-pencil/core'
 
-import { loadDocument, loadFonts, exportNodes, exportThumbnail } from '../headless'
 import { isAppMode, requireFile, rpc } from '../app-client'
 import { ok, printError } from '../format'
-import type { ExportFormat, JSXFormat } from '@open-pencil/core'
+import { loadDocument } from '../headless'
 
+import type { RasterExportFormat } from '@open-pencil/core'
+
+const io = new IORegistry(BUILTIN_IO_FORMATS)
 const RASTER_FORMATS = ['PNG', 'JPG', 'WEBP']
-const ALL_FORMATS = [...RASTER_FORMATS, 'SVG', 'JSX']
+const ALL_FORMATS = [...RASTER_FORMATS, 'SVG', 'JSX', 'FIG']
 const JSX_STYLES = ['openpencil', 'tailwind']
 
 interface ExportArgs {
@@ -34,17 +37,21 @@ async function writeAndLog(path: string, content: string | Uint8Array) {
 
 async function exportViaApp(format: string, args: ExportArgs) {
   if (format === 'SVG') {
-    const result = await rpc<{ svg: string }>('tool', { name: 'export_svg', args: { ids: args.node ? [args.node] : undefined } })
-    if (!result.svg) { printError('Nothing to export.'); process.exit(1) }
+    const result = await rpc<{ svg: string }>('tool', {
+      name: 'export_svg',
+      args: { ids: args.node ? [args.node] : undefined }
+    })
+    if (!result.svg) {
+      printError('Nothing to export.')
+      process.exit(1)
+    }
     await writeAndLog(resolve(args.output ?? 'export.svg'), result.svg)
     return
   }
 
-  if (format === 'JSX') {
-    const result = await rpc<{ jsx: string }>('export_jsx', { nodeIds: args.node ? [args.node] : undefined, style: args.style })
-    if (!result.jsx) { printError('Nothing to export.'); process.exit(1) }
-    await writeAndLog(resolve(args.output ?? 'export.jsx'), result.jsx)
-    return
+  if (format === 'JSX' || format === 'FIG') {
+    printError(`${format} export is only available in file mode right now.`)
+    process.exit(1)
   }
 
   const result = await rpc<{ base64: string }>('export', {
@@ -57,73 +64,122 @@ async function exportViaApp(format: string, args: ExportArgs) {
   await writeAndLog(resolve(args.output ?? `export.${ext}`), data)
 }
 
+function exportFileName(defaultName: string, extension: string, scale?: number): string {
+  return scale ? `${defaultName}@${scale}x.${extension}` : `${defaultName}.${extension}`
+}
+
+function targetLabel(pageName?: string, nodeId?: string): string {
+  if (nodeId) return `node ${nodeId}`
+  return pageName ? `page "${pageName}"` : 'first page'
+}
+
 async function exportFromFile(format: string, args: ExportArgs) {
   const file = requireFile(args.file)
   const graph = await loadDocument(file)
-  await loadFonts(graph)
 
   const pages = graph.getPages()
   const page = args.page ? pages.find((p) => p.name === args.page) : pages[0]
-  if (!page) { printError(`Page "${args.page}" not found.`); process.exit(1) }
+  if (!page) {
+    const available = pages.map((p) => `"${p.name}"`).join(', ')
+    printError(
+      args.page
+        ? `Page "${args.page}" not found. Available pages: ${available || 'none'}.`
+        : 'Document has no pages.'
+    )
+    process.exit(1)
+  }
 
   const defaultName = basename(file, extname(file))
 
-  if (format === 'JSX') {
-    const nodeIds = args.node ? [args.node] : page.childIds
-    const jsxStr = nodeIds.length === 1
-      ? sceneNodeToJSX(nodeIds[0], graph, args.style as JSXFormat)
-      : selectionToJSX(nodeIds, graph, args.style as JSXFormat)
-    if (!jsxStr) { printError('Nothing to export (empty page or no visible nodes).'); process.exit(1) }
-    await writeAndLog(resolve(args.output ?? `${defaultName}.jsx`), jsxStr)
-    return
+  if (args.page && args.node) {
+    printError('--page and --node cannot be used together.')
+    process.exit(1)
   }
 
-  const ext = format.toLowerCase() === 'jpg' ? 'jpg' : format.toLowerCase()
-  const output = resolve(args.output ?? `${defaultName}.${ext}`)
+  const target = args.node
+    ? { scope: 'node' as const, nodeId: args.node }
+    : { scope: 'page' as const, pageId: page.id }
 
-  if (format === 'SVG') {
-    const nodeIds = args.node ? [args.node] : page.childIds
-    const svgStr = renderNodesToSVG(graph, page.id, nodeIds)
-    if (!svgStr) { printError('Nothing to export (empty page or no visible nodes).'); process.exit(1) }
-    await writeAndLog(output, svgStr)
-    return
+  if (args.thumbnail) {
+    printError('Thumbnail export is not supported by the shared file export path yet.')
+    process.exit(1)
   }
 
-  let data: Uint8Array | null
-  if (args.thumbnail) {
-    data = await exportThumbnail(graph, page.id, Number(args.width), Number(args.height))
-  } else {
-    const nodeIds = args.node ? [args.node] : page.childIds
-    data = await exportNodes(graph, page.id, nodeIds, {
+  const formatId = format.toLowerCase()
+  let options: { format?: string; scale?: number; quality?: number } | undefined
+  if (format === 'JSX') {
+    options = { format: args.style }
+  } else if (format === 'PNG' || format === 'JPG' || format === 'WEBP') {
+    options = {
+      format,
       scale: Number(args.scale),
-      format: format as ExportFormat,
       quality: args.quality ? Number(args.quality) : undefined
-    })
+    }
   }
 
-  if (!data) { printError('Nothing to export (empty page or no visible nodes).'); process.exit(1) }
-  await writeAndLog(output, data)
+  const result = await io.exportContent(formatId, { graph, target }, options)
+  const output = resolve(
+    args.output ??
+      exportFileName(
+        defaultName,
+        result.extension,
+        format === 'PNG' || format === 'JPG' || format === 'WEBP' ? Number(args.scale) : undefined
+      )
+  )
+  await writeAndLog(output, result.data as string | Uint8Array)
+  console.log(ok(`Target: ${targetLabel(args.page, args.node)}`))
 }
 
 export default defineCommand({
-  meta: { description: 'Export a .fig file to PNG, JPG, WEBP, SVG, or JSX' },
+  meta: { description: 'Export a document to PNG, JPG, WEBP, SVG, JSX, or .fig' },
   args: {
-    file: { type: 'positional', description: '.fig file path (omit to connect to running app)', required: false },
-    output: { type: 'string', alias: 'o', description: 'Output file path (default: <name>.<format>)', required: false },
-    format: { type: 'string', alias: 'f', description: 'Export format: png, jpg, webp, svg, jsx (default: png)', default: 'png' },
+    file: {
+      type: 'positional',
+      description: 'Document file path (omit to connect to running app)',
+      required: false
+    },
+    output: {
+      type: 'string',
+      alias: 'o',
+      description: 'Output file path (default: <name>.<format>)',
+      required: false
+    },
+    format: {
+      type: 'string',
+      alias: 'f',
+      description: 'Export format: png, jpg, webp, svg, jsx, fig (default: png)',
+      default: 'png'
+    },
     scale: { type: 'string', alias: 's', description: 'Export scale (default: 1)', default: '1' },
-    quality: { type: 'string', alias: 'q', description: 'Quality 0-100 for JPG/WEBP (default: 90)', required: false },
-    page: { type: 'string', description: 'Page name (default: first page)', required: false },
-    node: { type: 'string', description: 'Node ID to export (default: all top-level nodes)', required: false },
-    style: { type: 'string', description: 'JSX style: openpencil, tailwind (default: openpencil)', default: 'openpencil' },
+    quality: {
+      type: 'string',
+      alias: 'q',
+      description: 'Quality 0-100 for JPG/WEBP (default: 90)',
+      required: false
+    },
+    page: {
+      type: 'string',
+      description: 'Export a specific page by name (default: first page)',
+      required: false
+    },
+    node: {
+      type: 'string',
+      description: 'Export a specific node by ID (cannot be combined with --page)',
+      required: false
+    },
+    style: {
+      type: 'string',
+      description: 'JSX style: openpencil, tailwind (default: openpencil)',
+      default: 'openpencil'
+    },
     thumbnail: { type: 'boolean', description: 'Export page thumbnail instead of full render' },
     width: { type: 'string', description: 'Thumbnail width (default: 1920)', default: '1920' },
     height: { type: 'string', description: 'Thumbnail height (default: 1080)', default: '1080' }
   },
   async run({ args }) {
-    const format = args.format.toUpperCase() as ExportFormat | 'JSX'
+    const format = args.format.toUpperCase() as RasterExportFormat | 'SVG' | 'JSX' | 'FIG'
     if (!ALL_FORMATS.includes(format)) {
-      printError(`Invalid format "${args.format}". Use png, jpg, webp, svg, or jsx.`)
+      printError(`Invalid format "${args.format}". Use png, jpg, webp, svg, jsx, or fig.`)
       process.exit(1)
     }