feat(cli): accept simple list inputs

Author: TheodoreSpeaks

packages/sim-cli/README.md

@@ -133,6 +133,8 @@ sim files list
 sim files create --name <name> [--content <value>] [--encoding utf-8|base64]
 sim files upload <path> [--name <name>] [--folder-id <id>]
 sim files download <fileId> [-o <path>]
+sim files move [--file-ids <id>…] [--folder-ids <id>…] [--target-folder-id <id>]
+sim files batch-archive [--file-ids <id>…] [--folder-ids <id>…] --yes
 sim files delete <fileId>
 
 sim knowledge list
@@ -142,6 +144,20 @@ sim knowledge documents upload <id> <path> [--tag <value>...]
 sim knowledge search --query <text> --kb <id>… [--search-mode vector|hybrid]
 ```
 
+### List inputs
+
+Primitive lists take space-separated values. Prefix a path with `@` to read
+one value per line, or use `@-` to read the list from stdin.
+
+```bash
+sim files move --file-ids file_1 file_2 --target-folder-id folder_1
+sim files move --file-ids @file-ids.txt --target-folder-id folder_1
+printf 'file_1\nfile_2\n' | sim files move --file-ids @- --target-folder-id folder_1
+```
+
+Arrays of objects remain JSON inputs because they cannot be represented as a
+flat list without losing structure.
+
 ### Filtering table rows
 
 `--filter` takes the same predicate tree the API uses — `all` (AND) or `any`

packages/sim-cli/src/contract/commands.ts

@@ -285,11 +285,19 @@ export const CLI_CONTRACT: CliContract = {
     // `batch-` for the bulk form, matching `tables rows batch-delete`.
     command: 'files batch-archive',
     describe: 'Archive several files and folders at once',
+    flags: {
+      fileIds: { list: true },
+      folderIds: { list: true },
+    },
     confirm: 'This archives every listed file and folder, and everything inside those folders.',
   },
   moveFileItems: {
     command: 'files move',
     describe: 'Move files and folders into another folder',
+    flags: {
+      fileIds: { list: true },
+      folderIds: { list: true },
+    },
   },
   renameFile: {
     // Derived to `files update`, which contradicted its own summary.
@@ -314,13 +322,23 @@ export const CLI_CONTRACT: CliContract = {
   upsertFileShare: {
     command: 'files share set',
     describe: 'Enable or disable sharing for a file',
+    flags: {
+      allowedEmails: { list: true },
+    },
   },
 
   // ─── The expanded tables surface ──────────────────────────────────────────
   // `/cancel-runs`, `/rows/find`, `/restore`, `/columns/run` and the enrichment
   // path all put a verb where the deriver expects a sub-resource, so each became
   // a group holding a lone `create`.
-  cancelTableRuns: { command: 'tables cancel-runs', describe: 'Stop every running column job' },
+  cancelTableRuns: {
+    command: 'tables cancel-runs',
+    describe: 'Stop every running column job',
+    flags: {
+      excludeRowIds: { list: true },
+      filter: { json: true, describe: TABLE_FILTER_HELP },
+    },
+  },
   findTableRows: {
     command: 'tables rows find',
     describe: 'Find rows matching a predicate',
@@ -336,7 +354,12 @@ export const CLI_CONTRACT: CliContract = {
   runTableColumn: {
     command: 'tables columns run',
     describe: 'Run a column’s workflow',
-    flags: { filter: { json: true, describe: TABLE_FILTER_HELP } },
+    flags: {
+      groupIds: { list: true },
+      rowIds: { list: true },
+      excludeRowIds: { list: true },
+      filter: { json: true, describe: TABLE_FILTER_HELP },
+    },
   },
   runRowEnrichment: {
     command: 'tables rows enrich',

packages/sim-cli/src/contract/types.ts

@@ -30,7 +30,8 @@ export interface FlagSpec {
   /** Short alias, e.g. `w` for `--workspace`. */
   short?: string
   /**
-   * Accept the flag more than once.
+   * Accept one or more space-separated values, or `@path` / `@-` with one
+   * value per line.
    *
    * Only says that several values are allowed — how they reach the wire is
    * decided by the field's kind, not here. A `string` field is one the route

packages/sim-cli/src/runtime/build.test.ts

@@ -155,6 +155,27 @@ describe('commands parsed through commander', () => {
     })
   })
 
+  it('accepts space-separated file and folder ids', async () => {
+    const [path, options] = await run([
+      'file',
+      'move',
+      '--file-ids',
+      'file_1',
+      'file_2',
+      '--folder-ids',
+      'folder_1',
+      '--target-folder-id',
+      'folder_2',
+    ])
+    expect(path).toBe('/api/v2/files/move')
+    expect(options.body).toEqual({
+      workspaceId: 'ws_local',
+      fileIds: ['file_1', 'file_2'],
+      folderIds: ['folder_1'],
+      targetFolderId: 'folder_2',
+    })
+  })
+
   it('exposes credential data centers added by the v2 credential contract', async () => {
     const [, options] = await run([
       'credential',
@@ -222,6 +243,12 @@ describe('commands parsed through commander', () => {
     expect(options.body).toMatchObject({ knowledgeBaseIds: ['kb_1'], searchMode: 'hybrid' })
   })
 
+  it('documents space-separated and file-backed lists', () => {
+    const help = commandAt('files', 'move').helpInformation()
+    expect(help).toContain('--file-ids <value...>')
+    expect(help).toMatch(/space-separated.*@path.*one value per line/s)
+  })
+
   it('advertises the file-content encoding choices', () => {
     expect(commandAt('files', 'set-content').helpInformation()).toMatch(
       /--encoding.*utf-8.*base64/s

packages/sim-cli/src/runtime/options.ts

@@ -59,9 +59,13 @@ function addFieldOption(
   const choices = flag.choices ?? descriptor.values
   const describe = `${
     flag.describe ?? (choices ? `One of: ${choices.join(', ')}` : `Set ${field}`)
-  }${wantsJson && !takesList ? ' (JSON, or @path / @- to read a file or stdin)' : ''}${
-    descriptor.required ? ' (required)' : ''
-  }`
+  }${
+    takesList
+      ? ' (space-separated, or @path / @- with one value per line)'
+      : wantsJson
+        ? ' (JSON, or @path / @- to read a file or stdin)'
+        : ''
+  }${descriptor.required ? ' (required)' : ''}`
 
   const option = new Option(`${short}--${name} ${placeholder}`, describe)
   if (choices && !takesList) option.choices([...choices])

packages/sim-cli/src/runtime/request.test.ts

@@ -142,6 +142,25 @@ describe('repeated flags encode per the field kind, not uniformly', () => {
     )
     expect(built.body?.knowledgeBaseIds).toEqual(['kb_1', 'kb_2'])
   })
+
+  it('reads one list value per line from @path', () => {
+    const path = join(tmpdir(), 'sim-cli-list-values.txt')
+    writeFileSync(path, 'file_1\nfile_2\n')
+    expect(coerce(`@${path}`, { kind: 'array' }, { list: true }, 'file-ids')).toEqual([
+      'file_1',
+      'file_2',
+    ])
+    rmSync(path)
+  })
+
+  it('rejects empty lines in a list file', () => {
+    const path = join(tmpdir(), 'sim-cli-list-empty-line.txt')
+    writeFileSync(path, 'file_1\n\nfile_2')
+    expect(() => coerce(`@${path}`, { kind: 'array' }, { list: true }, 'file-ids')).toThrow(
+      /empty value on line 2/
+    )
+    rmSync(path)
+  })
 })
 
 describe('contract-provided choices', () => {

packages/sim-cli/src/runtime/request.ts

@@ -77,16 +77,16 @@ function readStdin(): string {
 }
 
 /**
- * Resolves a JSON flag's argument, which may name a file instead of carrying
- * the document inline.
+ * Resolves a flag argument that may name a file instead of carrying its value
+ * inline.
  *
  * `@path` reads the file and `@-` reads stdin, the curl convention. A workflow
  * export is hundreds of lines, and the shell makes passing that literally
  * unpleasant — unquoted `$(cat f.json)` word-splits into broken JSON, and the
- * quoted form is easy to get wrong. `@` cannot collide with a real value
- * because JSON only ever starts with `{ [ " -`, a digit, or t/f/n.
+ * quoted form is easy to get wrong. JSON never starts with `@`; primitive list
+ * flags reserve it for this explicit file-input form.
  */
-function readJsonArgument(raw: string, flagName: string): { text: string; from: string } {
+function readArgumentSource(raw: string, flagName: string): { text: string; from: string } {
   if (!raw.startsWith('@')) return { text: raw, from: '' }
 
   const path = raw.slice(1)
@@ -108,6 +108,42 @@ function readJsonArgument(raw: string, flagName: string): { text: string; from:
   }
 }
 
+/** Reads a primitive list from argv or a newline-delimited file. */
+function readListValues(raw: unknown, flagName: string): string[] {
+  const arguments_ = Array.isArray(raw) ? raw : [raw]
+  const values = arguments_.flatMap((argument) => {
+    if (typeof argument !== 'string') {
+      throw new SimApiError(`--${flagName} values must be strings`, 0)
+    }
+
+    if (!argument.startsWith('@')) return [argument]
+
+    const source = readArgumentSource(argument, flagName)
+    const lines = source.text.split(/\r?\n/)
+    if (lines.at(-1) === '') lines.pop()
+    if (lines.length === 0) {
+      throw new SimApiError(`--${flagName}${source.from} contains no values`, 0)
+    }
+
+    return lines.map((line, index) => {
+      const value = line.trim()
+      if (!value) {
+        throw new SimApiError(
+          `--${flagName}${source.from} has an empty value on line ${index + 1}`,
+          0
+        )
+      }
+      return value
+    })
+  })
+
+  return values.map((value) => {
+    const trimmed = value.trim()
+    if (!trimmed) throw new SimApiError(`--${flagName} values cannot be empty`, 0)
+    return trimmed
+  })
+}
+
 /**
  * Points at `@` when a value that failed to parse looks like a filename.
  *
@@ -144,13 +180,13 @@ export function coerce(raw: unknown, field: FieldSpec, flag: FlagSpec, flagName:
    *   or failed validation outright.
    */
   if (flag.list) {
-    const values = Array.isArray(raw) ? raw : [raw]
+    const values = readListValues(raw, flagName)
     return field.kind === 'string' ? values.join(',') : values
   }
 
   if (takesJson(field, flag)) {
     if (typeof raw !== 'string') return raw
-    const source = readJsonArgument(raw, flagName)
+    const source = readArgumentSource(raw, flagName)
     try {
       return JSON.parse(source.text)
     } catch (error) {