feat(cli): streamline common resource workflows

Author: TheodoreSpeaks

packages/sim-cli/README.md

@@ -3,7 +3,7 @@
 Talk to the [Sim](https://sim.ai) API from your terminal.
 
 ```bash
-npm install -g @sim/cli
+bun add --global @sim/cli
 sim login
 sim workflows list
 ```
@@ -53,7 +53,7 @@ Each setting resolves independently, first match wins:
 
 | Rank | Source |
 | --- | --- |
-| 1 | Command-line flag (`--endpoint`, `--workspace`) |
+| 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) |
 | 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) |
 | 3 | `~/.sim/config` / `~/.sim/credentials` for the selected profile |
 | 4 | Built-in default (`https://sim.ai`, `table`) |
@@ -112,12 +112,15 @@ also accepts its singular form: for example, `sim table list`,
 `sim file download`, and `sim workflow get` are equivalent to their plural
 spellings.
 
+`knowledge` also accepts the shorter `kb` alias.
+
 ```bash
 sim workflows ls [path] [--search <text>] [--limit <n>]
 sim workflows list [--folder <path>] [--deployed-only] [--limit <n>]
 sim workflows get <id>
 sim workflows mv <id> --folder <path>
 sim workflows deploy|undeploy|rollback <id>
+sim workflows run <id> [--input <json|@file>] [--select-output <path>…]
 
 sim logs list [--level error] [--workflow <id>…] [--trigger <name>…] [--start <date>]
 sim logs get <id>
@@ -129,7 +132,10 @@ sim tables get <tableId>
 sim tables mv <tableId> --folder <path>
 sim tables columns <tableId>
 sim tables rows list <tableId> [--limit <n>]
+sim tables rows create <tableId> --data <json|@file>
+sim tables rows create <tableId> --rows <json|@file>
 sim tables rows query <tableId> [--filter <json>] [--sort <json>] [--limit <n>]
+sim tables rows query <tableId> --filter '{"all":[{"field":"status","op":"eq","value":"active"}]}'
 sim tables upsert <tableId> --data <json>
 sim tables rows batch-delete <tableId> (--row <id>… | --filter <json>) --yes
 
@@ -138,10 +144,10 @@ sim files list [--folder <path>]
 sim files get <fileId>
 sim files create --name <name> [--folder <path>] [--content <value>] [--encoding utf-8|base64]
 sim files upload <path> [--name <name>] [--folder <path>]
-sim files download <fileId> [-o <path>]
+sim files download <fileId> [-o <path|->]
 sim files mv --file-ids <id>… [--to <path>]
 sim files batch-delete --file-ids <id>… --yes
-sim files delete <fileId>
+sim files delete <fileId> --yes
 
 sim knowledge ls [path] [--search <text>] [--limit <n>]
 sim knowledge list [--folder <path>]
@@ -150,8 +156,14 @@ sim knowledge mv <id> --folder <path>
 sim knowledge documents <id> [--search <text>]
 sim knowledge documents upload <id> <path> [--tag <value>...]
 sim knowledge search --query <text> --kb <id>… [--search-mode vector|hybrid]
+
+sim billing
+sim billing logs [--period 7d] [--limit <n>]
 ```
 
+Workflow output selectors use `blockName.field` syntax, such as
+`--select-output agent_1.content`; fields that are not produced are omitted.
+
 `ls` is a directory view: it combines the resources at its optional path with
 that folder's direct child folders. It never includes deeper descendants. Its
 `ref` column is the resource ID or canonical folder path to pass to the next
@@ -166,14 +178,13 @@ sim tables folders ls --parent Reports
 sim tables mkdir Reports/Quarterly
 sim tables folders create Reports/Quarterly
 sim tables folders mv Reports/Quarterly Archive/Quarterly
-sim tables folders delete Archive/Quarterly --recursive false --yes
+sim tables folders delete Archive/Quarterly --yes
+sim tables folders delete Archive --recursive --yes
 ```
 
 `mkdir` is the concise form of `folders create`. Replace `tables` with `files`,
-`workflows`, or `knowledge`. The leading `/` is optional on CLI inputs; the CLI
-adds it before calling the API. Omit the `ls` path to list root. A slash that
-belongs to a folder name is percent-encoded as `%2F` rather than treated as a
-separator.
+`workflows`, or `knowledge`. The leading `/` is optional on API inputs; the API
+returns the canonical leading-slash form. Omit the `ls` path to list root.
 
 ### List inputs
 
@@ -210,9 +221,9 @@ everything" default.
 
 ### Output formats
 
-Output format is a **profile setting**, not a per-command flag — there is no
-`--output`. Set it once with `sim configure --set-output <format>`, or override
-ambiently with `SIM_OUTPUT` for a one-off or for CI:
+Output format can be selected per command with `--output`, saved as a profile
+default with `sim configure --set-output <format>`, or set ambiently with
+`SIM_OUTPUT` for CI:
 
 | Format | For |
 | --- | --- |
@@ -230,7 +241,8 @@ parsing.
 sim configure --set-output json                      # for this profile, from now on
 sim configure --set-output text --profile scripts    # a profile dedicated to scripting
 
-SIM_OUTPUT=json sim logs list --level error | jq -r '.[].executionId'
+sim --output json logs list --level error | jq -r '.[].executionId'
+sim logs list --level error --output json | jq -r '.[].executionId'
 SIM_OUTPUT=yaml sim logs list --level error > logs.yaml
 
 SIM_OUTPUT=text sim files list | while IFS=$'\t' read -r id name size type uploaded; do
@@ -241,9 +253,9 @@ done
 An absent value is an em-dash in `table` and an **empty field** in `text`, so
 emptiness tests downstream behave.
 
-A bad `SIM_OUTPUT` or `output =` is ignored and falls back to `table`. Both are
-ambient — set once, then read by every later command — so one bad value should
-not break the CLI outright.
+An invalid active `SIM_OUTPUT` or `output =` value fails with the accepted
+formats. A valid higher-priority `--output` still overrides a stale lower tier,
+so `sim --output table configure --set-output json` can repair a profile.
 
 ## How this stays in sync with the API
 

packages/sim-cli/src/commands/protocol/files-download.test.ts

@@ -102,6 +102,35 @@ describe('files download', () => {
       target,
     ])
 
-    expect(JSON.parse(logged[0])).toEqual({ id: 'file_1', path: target, status: 'saved' })
+    expect(JSON.parse(logged[0])).toEqual({
+      id: 'file_1',
+      path: target,
+      status: 'saved',
+    })
+  })
+
+  it('streams raw bytes to stdout with the conventional - destination', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('downloaded', { status: 200 })))
+    const chunks: Uint8Array[] = []
+    vi.spyOn(process.stdout, 'write').mockImplementation((chunk: string | Uint8Array) => {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+      return true
+    })
+    const logged = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await program().parseAsync(['node', 'sim', 'file', 'download', 'file_1', '-o', '-'])
+
+    expect(Buffer.concat(chunks).toString('utf8')).toBe('downloaded')
+    expect(logged).not.toHaveBeenCalled()
+  })
+
+  it('rejects overwrite semantics for stdout', async () => {
+    const fetch = vi.fn()
+    vi.stubGlobal('fetch', fetch)
+
+    await expect(
+      program().parseAsync(['node', 'sim', 'file', 'download', 'file_1', '-o', '-', '--force'])
+    ).rejects.toThrow(/--force cannot be used/)
+    expect(fetch).not.toHaveBeenCalled()
   })
 })

packages/sim-cli/src/commands/protocol/files-download.ts

@@ -47,18 +47,39 @@ export async function streamToFile(
   }
 }
 
+/** Streams a fetch body to stdout without closing the process-wide stream. */
+export async function streamToStdout(
+  body: ReadableStream<Uint8Array>,
+  output: NodeJS.WriteStream = process.stdout
+): Promise<void> {
+  const reader = body.getReader()
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) return
+      if (!output.write(value)) await once(output, 'drain')
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
 export function attachFileDownload(files: Command): void {
   files
     .command('download <fileId>')
     .description('Download a file')
-    .option('-o, --output-file <path>', 'Where to write it (defaults to the file name)')
+    .option('-o, --output-file <path>', 'Where to write it (default: file name; -: stdout)')
     .option('--force', 'Overwrite the destination if it already exists')
     .action(
       async (
         fileId: string,
         options: { outputFile?: string; force?: boolean },
         command: Command
       ) => {
+        if (options.outputFile === '-' && options.force) {
+          throw new SimApiError('--force cannot be used when --output-file is -', 0)
+        }
+
         const { client, profile } = clientFrom(command)
         const workspaceId = client.requireWorkspace()
 
@@ -70,7 +91,9 @@ export function attachFileDownload(files: Command): void {
         url.searchParams.set('workspaceId', workspaceId)
 
         // boundary-raw-fetch: binary download cannot pass through the JSON client
-        const response = await fetch(url, { headers: { 'x-api-key': profile.apiKey } })
+        const response = await fetch(url, {
+          headers: { 'x-api-key': profile.apiKey },
+        })
         if (!response.ok || !response.body) {
           const raw = await response.text().catch(() => '')
           throw new SimApiError(
@@ -79,6 +102,11 @@ export function attachFileDownload(files: Command): void {
           )
         }
 
+        if (options.outputFile === '-') {
+          await streamToStdout(response.body)
+          return
+        }
+
         const target =
           options.outputFile ??
           basename(
@@ -90,7 +118,11 @@ export function attachFileDownload(files: Command): void {
           response.body,
           createWriteStream(target, { flags: options.force ? 'w' : 'wx' })
         )
-        printProtocolResult(profile.output, { id: fileId, path: target, status: 'saved' })
+        printProtocolResult(profile.output, {
+          id: fileId,
+          path: target,
+          status: 'saved',
+        })
       }
     )
 }

packages/sim-cli/src/commands/protocol/files-upload.test.ts

@@ -44,7 +44,7 @@ function program(): Command {
 }
 
 describe('files upload', () => {
-  it('uses a signed PUT transfer and completes with an empty body', async () => {
+  it('uses a signed PUT transfer and completes without a request body', async () => {
     const path = join(dir, 'notes.txt')
     writeFileSync(path, 'hello')
     mockRequest
@@ -114,7 +114,7 @@ describe('files upload', () => {
           name: 'notes.txt',
           contentType: 'text/plain',
           size: 5,
-          folderPath: '/Reports',
+          folderPath: 'Reports',
         },
       },
     ])
@@ -124,14 +124,18 @@ describe('files upload', () => {
         method: 'POST',
         query: { workspaceId: 'ws_local' },
         headers: { 'upload-token': 'secret-token' },
-        body: {},
       },
     ])
     expect(JSON.parse(logged[0])).toEqual({
       id: 'file_1',
       name: 'notes.txt',
       size: 5,
-      status: 'uploaded',
+      type: 'text/plain',
+      key: 'workspace/ws_local/notes.txt',
+      folderPath: '/',
+      uploadedBy: 'user_1',
+      uploadedAt: '2026-08-04T19:00:00.000Z',
+      updatedAt: '2026-08-04T19:00:00.000Z',
     })
     expect(logged[0]).not.toContain('secret-token')
   })

packages/sim-cli/src/commands/protocol/files-upload.ts

@@ -4,7 +4,6 @@ import type {
   CompleteFileUploadResponse,
   CreateFileUploadResponse,
 } from '../../generated/v2-api.js'
-import { normalizeFolderPath } from '../../runtime/folder-path.js'
 import { contentTypeFor, localFile } from '../../transfer/local-file.js'
 import { finishUploadSession } from '../../transfer/upload-session.js'
 import { printProtocolResult } from './result.js'
@@ -13,7 +12,7 @@ export function attachFileUpload(files: Command): void {
   files
     .command('upload <path>')
     .description('Upload a file to the workspace')
-    .option('--folder <path>', 'Canonical destination folder path (defaults to /)')
+    .option('--folder <path>', 'Destination folder path (defaults to /)')
     .option('--name <name>', 'Store it under a different name')
     .action(async (path: string, options: { folder?: string; name?: string }, command: Command) => {
       const { client, profile } = clientFrom(command)
@@ -27,9 +26,7 @@ export function attachFileUpload(files: Command): void {
           name,
           contentType: contentTypeFor(name),
           size,
-          ...(options.folder !== undefined
-            ? { folderPath: normalizeFolderPath(options.folder) }
-            : {}),
+          ...(options.folder !== undefined ? { folderPath: options.folder } : {}),
         },
       })
       const { session, uploadToken, transfer } = created.data
@@ -45,11 +42,9 @@ export function attachFileUpload(files: Command): void {
         path
       )
 
-      printProtocolResult(profile.output, {
-        id: completed.file?.id ?? session.id,
-        name,
-        size,
-        status: 'uploaded',
-      })
+      if (!completed.file) {
+        throw new Error(`File upload ${session.id} completed without a file`)
+      }
+      printProtocolResult(profile.output, completed.file)
     })
 }

packages/sim-cli/src/commands/protocol/knowledge-document-upload.test.ts

@@ -166,8 +166,10 @@ describe('knowledge documents upload', () => {
     expect(mockRequest.mock.calls[2][0]).toBe(
       '/api/v2/knowledge/kb_1/documents/uploads/upload_1/complete'
     )
-    expect(mockRequest.mock.calls[2][1].body).toEqual({
-      parts: [{ partNumber: 1, etag: 'etag-1' }],
+    expect(mockRequest.mock.calls[2][1]).toEqual({
+      method: 'POST',
+      query: { workspaceId: 'ws_local' },
+      headers: { 'upload-token': 'secret-token' },
     })
     expect(JSON.parse(logged[0])).toEqual({
       id: 'doc_1',

packages/sim-cli/src/commands/protocol/resource-directory.test.ts

@@ -87,7 +87,7 @@ describe('resource directory', () => {
     expect(mockRequest).toHaveBeenCalledWith('/api/v2/tables/folders', {
       query: {
         workspaceId: 'ws_local',
-        parentPath: '/Reports',
+        parentPath: 'Reports',
         search: 'r',
         sortBy: 'name',
         sortOrder: 'asc',
@@ -96,7 +96,7 @@ describe('resource directory', () => {
     expect(mockRequest).toHaveBeenCalledWith('/api/v2/tables', {
       query: {
         workspaceId: 'ws_local',
-        folderPath: '/Reports',
+        folderPath: 'Reports',
         search: 'r',
         sortBy: 'name',
         sortOrder: 'asc',
@@ -140,7 +140,7 @@ describe('resource directory', () => {
 
     expect(mockRequest).toHaveBeenCalledWith('/api/v2/tables/folders', {
       method: 'POST',
-      body: { workspaceId: 'ws_local', path: '/Reports/Quarterly' },
+      body: { workspaceId: 'ws_local', path: 'Reports/Quarterly' },
     })
   })
 

packages/sim-cli/src/commands/protocol/resource-directory.ts

@@ -14,7 +14,6 @@ import {
 } from '../../generated/v2-api.js'
 import { SimApiError, type SimClient, type V2Page } from '../../http/client.js'
 import { type Column, printList, text, timestamp } from '../../output/render.js'
-import { normalizeFolderPath } from '../../runtime/folder-path.js'
 import { DEFAULT_LIMIT } from '../../runtime/options.js'
 import { renderResult } from '../../runtime/result.js'
 
@@ -179,7 +178,7 @@ export function attachResourceDirectoryCommands(
       }
 
       const limit = rawLimit === 0 ? Number.POSITIVE_INFINITY : rawLimit
-      const folderPath = normalizeFolderPath(path ?? '/')
+      const folderPath = path ?? '/'
       const { client, profile } = clientFrom(command)
       const workspaceId = client.requireWorkspace()
       const [folders, resources] = await Promise.all([
@@ -193,13 +192,13 @@ export function attachResourceDirectoryCommands(
   group
     .command('mkdir <path>')
     .allowExcessArguments(false)
-    .description(`Create a ${config.kind} directory at a canonical path`)
+    .description(`Create a ${config.kind} directory at a path`)
     .action(async (path: string, _options: Record<string, never>, command: Command) => {
       const { client, profile } = clientFrom(command)
       const operation = V2_OPERATIONS[config.createFolder]
       const result = await client.request<{ data?: unknown }>(operation.path, {
         method: operation.method,
-        body: { workspaceId: client.requireWorkspace(), path: normalizeFolderPath(path) },
+        body: { workspaceId: client.requireWorkspace(), path },
       })
       renderResult(config.createFolder, profile.output, result.data ?? result, {})
     })