feat(cli): standardize resource command syntax

Author: TheodoreSpeaks

packages/sim-cli/README.md

@@ -112,13 +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.
+`knowledge` also accepts the shorter `kb` alias, and `documents` accepts
+`document`.
 
 ```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 update <id> [--name <name>] [--description <text>] [--folder <path>]
+sim workflows mv <id> <folder>
 sim workflows deploy|undeploy|rollback <id>
 sim workflows run <id> [--input <json|@file>] [--select-output <path>…]
 
@@ -129,7 +131,8 @@ sim logs execution <executionId>
 sim tables ls [path] [--search <text>] [--limit <n>]
 sim tables list [--folder <path>]
 sim tables get <tableId>
-sim tables mv <tableId> --folder <path>
+sim tables update <tableId> [--name <name>] [--description <text>] [--folder <path>]
+sim tables mv <tableId> <folder>
 sim tables columns <tableId>
 sim tables rows list <tableId> [--limit <n>]
 sim tables rows create <tableId> --data <json|@file>
@@ -152,11 +155,15 @@ sim files delete <fileId> --yes
 sim knowledge ls [path] [--search <text>] [--limit <n>]
 sim knowledge list [--folder <path>]
 sim knowledge get <id>
-sim knowledge mv <id> --folder <path>
-sim knowledge documents <id> [--search <text>]
-sim knowledge documents upload <id> <path> [--tag <value>...]
+sim knowledge update <id> [--name <name>] [--description <text>] [--folder <path>]
+sim knowledge mv <id> <folder>
 sim knowledge search --query <text> --kb <id>… [--search-mode vector|hybrid]
 
+sim documents list --kb <knowledgeBaseId> [--search <text>]
+sim documents get <documentId> --kb <knowledgeBaseId>
+sim documents upload <path> --kb <knowledgeBaseId> [--tag <value>...]
+sim documents delete <documentId> --kb <knowledgeBaseId> --yes
+
 sim billing
 sim billing logs [--period 7d] [--limit <n>]
 ```

packages/sim-cli/src/commands/protocol/index.ts

@@ -25,8 +25,9 @@ export function attachProtocolCommands(program: Command): void {
     createFolder: 'createFileFolder',
   })
 
+  attachKnowledgeDocumentUpload(group(program, 'documents'))
+
   const knowledge = group(program, 'knowledge')
-  attachKnowledgeDocumentUpload(group(knowledge, 'documents'))
   attachResourceDirectoryCommands(knowledge, {
     kind: 'knowledge',
     resources: 'listKnowledgeBases',

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

@@ -62,14 +62,16 @@ function uploadSession() {
   }
 }
 
-describe('knowledge documents upload', () => {
+describe('documents upload', () => {
   it('owns the multipart protocol while hiding its low-level operations', () => {
-    const knowledge = program().commands.find((command) => command.name() === 'knowledge')
+    const root = program()
+    const knowledge = root.commands.find((command) => command.name() === 'knowledge')
     expect(knowledge?.commands.map((command) => command.name())).not.toEqual(
-      expect.arrayContaining(['uploads', 'parts', 'complete'])
+      expect.arrayContaining(['documents', 'uploads', 'parts', 'complete'])
     )
 
-    const documents = knowledge?.commands.find((command) => command.name() === 'documents')
+    const documents = root.commands.find((command) => command.name() === 'documents')
+    expect(documents?.alias()).toBe('document')
     expect(documents?.commands.map((command) => command.name())).toContain('upload')
   })
 
@@ -131,11 +133,11 @@ describe('knowledge documents upload', () => {
     await program().parseAsync([
       'node',
       'sim',
-      'knowledge',
       'documents',
       'upload',
-      'kb_1',
       path,
+      '--kb',
+      'kb_1',
       '--tag',
       'customer',
       'priority',
@@ -189,11 +191,11 @@ describe('knowledge documents upload', () => {
       program().parseAsync([
         'node',
         'sim',
-        'knowledge',
         'documents',
         'upload',
-        'kb_1',
         path,
+        '--kb',
+        'kb_1',
         '--tag',
         '1',
         '2',
@@ -207,4 +209,14 @@ describe('knowledge documents upload', () => {
     ).rejects.toThrow(/at most seven/)
     expect(mockRequest).not.toHaveBeenCalled()
   })
+
+  it('requires an explicit knowledge-base scope before reading the file', async () => {
+    const path = join(dir, 'notes.txt')
+    writeFileSync(path, 'hello')
+
+    await expect(
+      program().parseAsync(['node', 'sim', 'documents', 'upload', path])
+    ).rejects.toThrow(/required option '--kb <knowledgeBaseId>'/)
+    expect(mockRequest).not.toHaveBeenCalled()
+  })
 })

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

@@ -10,6 +10,7 @@ import { finishUploadSession } from '../../transfer/upload-session.js'
 import { printProtocolResult } from './result.js'
 
 interface KnowledgeDocumentUploadOptions {
+  kb: string
   name?: string
   tag?: string[]
   recipe?: string
@@ -37,62 +38,54 @@ function uploadMetadata(options: KnowledgeDocumentUploadOptions): Record<string,
 
 export function attachKnowledgeDocumentUpload(documents: Command): void {
   documents
-    .command('upload <knowledgeBaseId> <path>')
+    .command('upload <path>')
     .description('Upload a document to a knowledge base')
+    .requiredOption('--kb <knowledgeBaseId>', 'Knowledge base ID (required)')
     .option('--name <name>', 'Store it under a different name')
     .option('--tag <value...>', 'Document tags, in tag1 through tag7 order')
     .option('--recipe <name>', 'Document processing recipe')
     .option('--lang <code>', 'Document language code')
-    .action(
-      async (
-        knowledgeBaseId: string,
-        path: string,
-        options: KnowledgeDocumentUploadOptions,
-        command: Command
-      ) => {
-        const { client, profile } = clientFrom(command)
-        const workspaceId = client.requireWorkspace()
-        const { name, size } = await localFile(path, options.name)
-        const created = await client.request<CreateKnowledgeDocumentUploadResponse>(
-          `/api/v2/knowledge/${encodeURIComponent(knowledgeBaseId)}/documents/uploads`,
-          {
-            method: 'POST',
-            body: {
-              workspaceId,
-              name,
-              contentType: contentTypeFor(name),
-              size,
-              ...uploadMetadata(options),
-            },
-          }
-        )
-        const { session, uploadToken, transfer } = created.data
-        const completed = await finishUploadSession<
-          CompleteKnowledgeDocumentUploadResponse['data']
-        >(
-          client,
-          workspaceId,
-          {
-            basePath: `/api/v2/knowledge/${encodeURIComponent(
-              knowledgeBaseId
-            )}/documents/uploads/${encodeURIComponent(session.id)}`,
-            uploadToken,
-            transfer,
+    .action(async (path: string, options: KnowledgeDocumentUploadOptions, command: Command) => {
+      const { client, profile } = clientFrom(command)
+      const workspaceId = client.requireWorkspace()
+      const { name, size } = await localFile(path, options.name)
+      const created = await client.request<CreateKnowledgeDocumentUploadResponse>(
+        `/api/v2/knowledge/${encodeURIComponent(options.kb)}/documents/uploads`,
+        {
+          method: 'POST',
+          body: {
+            workspaceId,
+            name,
+            contentType: contentTypeFor(name),
             size,
+            ...uploadMetadata(options),
           },
-          path
-        )
-
-        if (!completed.document) {
-          throw new Error(`Knowledge upload ${session.id} completed without a document`)
         }
-        printProtocolResult(profile.output, {
-          id: completed.document.id,
-          knowledgeBaseId: completed.document.knowledgeBaseId,
-          name: completed.document.filename,
-          size: completed.document.fileSize,
-          status: completed.document.processingStatus,
-        })
+      )
+      const { session, uploadToken, transfer } = created.data
+      const completed = await finishUploadSession<CompleteKnowledgeDocumentUploadResponse['data']>(
+        client,
+        workspaceId,
+        {
+          basePath: `/api/v2/knowledge/${encodeURIComponent(
+            options.kb
+          )}/documents/uploads/${encodeURIComponent(session.id)}`,
+          uploadToken,
+          transfer,
+          size,
+        },
+        path
+      )
+
+      if (!completed.document) {
+        throw new Error(`Knowledge upload ${session.id} completed without a document`)
       }
-    )
+      printProtocolResult(profile.output, {
+        id: completed.document.id,
+        knowledgeBaseId: completed.document.knowledgeBaseId,
+        name: completed.document.filename,
+        size: completed.document.fileSize,
+        status: completed.document.processingStatus,
+      })
+    })
 }

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

@@ -1,4 +1,4 @@
-import type { CliContract, ColumnSpec } from './types.js'
+import type { CliContract, ColumnSpec, CommandVariantSpec } from './types.js'
 
 const TABLE_NAME_HELP = 'Identifier: letters, numbers, and underscores; cannot start with a number'
 const TABLE_FILTER_HELP =
@@ -18,13 +18,29 @@ const FOLDER_DELETE_FLAGS = {
   path: FOLDER_PATH_INPUT,
   recursive: { boolean: true, describe: 'Delete the folder and its descendants' },
 } as const
+const KNOWLEDGE_DOCUMENT_SCOPE = {
+  id: {
+    name: 'kb',
+    placeholder: 'knowledgeBaseId',
+    describe: 'Knowledge base ID',
+  },
+} as const
 const FOLDER_LIST_COLUMNS: ColumnSpec[] = [
   { header: 'path' },
   { header: 'name' },
   { header: 'parent', path: 'parentPath' },
   { header: 'updated', path: 'updatedAt', format: 'timestamp' },
 ]
 
+function moveResource(command: string, resource: string): CommandVariantSpec {
+  return {
+    command,
+    positionals: ['folderPath'],
+    requestFields: ['folderPath'],
+    describe: `Move a ${resource} to a folder`,
+  }
+}
+
 /**
  * The CLI contract for the v2 surface.
  *
@@ -34,7 +50,7 @@ const FOLDER_LIST_COLUMNS: ColumnSpec[] = [
  *
  * Derived by default:
  *   listTables            → sim tables list
- *   getKnowledgeDocument  → sim knowledge documents get <id> <documentId>
+ *   getKnowledgeDocument  → sim documents get <documentId> --kb <knowledgeBaseId>
  *   upsertTableRow        → sim tables upsert <tableId>
  */
 export const CLI_CONTRACT: CliContract = {
@@ -54,6 +70,12 @@ export const CLI_CONTRACT: CliContract = {
   listUsageLogs: {
     command: 'billing logs',
     describe: 'List credit usage events',
+    flags: {
+      source: { describe: 'Filter by usage source' },
+      period: { describe: 'Billing period' },
+      startDate: { describe: 'Custom period start (ISO 8601)' },
+      endDate: { describe: 'Custom period end (ISO 8601)' },
+    },
     columns: [
       { header: 'at', path: 'createdAt', format: 'timestamp' },
       { header: 'source' },
@@ -99,7 +121,11 @@ export const CLI_CONTRACT: CliContract = {
     fields: [{ header: 'remaining columns', path: 'columns', format: 'count' }],
   },
   deleteKnowledgeBase: { confirm: 'This deletes the knowledge base and every document in it.' },
-  deleteKnowledgeDocument: { confirm: 'This deletes the document and its embeddings.' },
+  deleteKnowledgeDocument: {
+    command: 'documents delete',
+    pathFlags: KNOWLEDGE_DOCUMENT_SCOPE,
+    confirm: 'This deletes the document and its embeddings.',
+  },
   deleteFile: { confirm: 'This archives the file.' },
   deleteSkill: { confirm: 'This deletes the skill.' },
   deleteCustomTool: { confirm: 'This deletes the custom tool.' },
@@ -223,17 +249,23 @@ export const CLI_CONTRACT: CliContract = {
     },
   },
   updateTable: {
-    aliases: ['mv'],
+    variants: [moveResource('tables mv', 'table')],
     flags: {
       name: { describe: TABLE_NAME_HELP },
       folderPath: FOLDER_PATH_FLAG,
     },
   },
   createFile: { flags: { folderPath: FOLDER_PATH_FLAG } },
   createKnowledgeBase: { flags: { folderPath: FOLDER_PATH_FLAG } },
-  updateKnowledgeBase: { aliases: ['mv'], flags: { folderPath: FOLDER_PATH_FLAG } },
+  updateKnowledgeBase: {
+    variants: [moveResource('knowledge mv', 'knowledge base')],
+    flags: { folderPath: FOLDER_PATH_FLAG },
+  },
   createWorkflow: { flags: { folderPath: FOLDER_PATH_FLAG } },
-  updateWorkflow: { aliases: ['mv'], flags: { folderPath: FOLDER_PATH_FLAG } },
+  updateWorkflow: {
+    variants: [moveResource('workflows mv', 'workflow')],
+    flags: { folderPath: FOLDER_PATH_FLAG },
+  },
   importWorkflow: { flags: { folderPath: FOLDER_PATH_FLAG } },
   createCustomTool: { flags: { schema: { json: true, describe: CUSTOM_TOOL_SCHEMA_HELP } } },
   updateCustomTool: { flags: { schema: { json: true, describe: CUSTOM_TOOL_SCHEMA_HELP } } },
@@ -285,7 +317,13 @@ export const CLI_CONTRACT: CliContract = {
       { header: 'model', path: 'embeddingModel' },
     ],
   },
+  getKnowledgeDocument: {
+    command: 'documents get',
+    pathFlags: KNOWLEDGE_DOCUMENT_SCOPE,
+  },
   listKnowledgeDocuments: {
+    command: 'documents list',
+    pathFlags: KNOWLEDGE_DOCUMENT_SCOPE,
     columns: [
       { header: 'id' },
       { header: 'filename' },
@@ -601,7 +639,7 @@ export const CLI_CONTRACT: CliContract = {
   },
 
   // ─── Not a terminal-shaped operation ──────────────────────────────────────
-  // Multipart upload; `sim knowledge documents upload <id> <path>` needs its
+  // Multipart upload; `sim documents upload <path> --kb <id>` needs its
   // own file-reading command rather than a generated flag surface.
   uploadKnowledgeDocument: { hidden: true },
   createKnowledgeDocumentUpload: { hidden: true },