feat(cli): generate the CLI's v2 API from the route contracts, add tables

The same endpoint was being described in three hand-maintained places: the Zod
contracts the routes validate against, the OpenAPI documents, and the CLI's own
TypeScript interfaces. Two of those are now derived.

`scripts/generate-v2-cli-api.ts` reads `apps/sim/lib/api/contracts/v2/**` and
emits `packages/sim-cli/src/generated/v2-api.ts`: request/response types for all
44 operations plus an operation table (method, path, path params) the client
dispatches through, so a route that moves or changes verb moves the CLI with it.

The contracts are the right source because the routes validate against them — a
shape that disagrees with a contract is a shape the server would reject. Zod
4's `z.toJSONSchema()` handles all 110 schema slots; the JSON-Schema-to-TS
emitter is hand-rolled over that known-narrow subset and throws on anything
unrecognized rather than degrading to `any`, since silence is how a generated
client drifts.

`packages/*` must not import `apps/*`, so the generated file is plain type
declarations with no imports and the script does the crossing at build time.

`check:cli-api` fails CI when the file is stale. The generated directory is
excluded from biome: the pre-commit hook runs `check --write`, which would
otherwise reformat generated output and fail that check with an unrelated
message.

The docs specs carry ~1000 hand-written descriptions and ~400 examples that Zod
schemas do not encode, so generating them would trade real documentation for
mechanical accuracy. `check:openapi-drift` reconciles structure instead — every
v2 path and method must exist on both sides — keeping the prose while still
failing on divergence. Both currently agree on all 44 operations.

`sim tables list|get|columns|rows|insert|delete-rows`, built on the generated
types. Rows go through the POST query endpoint even unfiltered, since it is the
only shape carrying the predicate. Row columns are discovered at runtime and
unioned across the page, so a sparse row cannot hide a column.

Deletion requires an explicit `--row`/`--filter` selector *and* `--yes`; an
argument-less call would otherwise empty the table. Path params are
percent-encoded — an id containing `/` or `?` would otherwise retarget the
request.

The four existing command groups drop their hand-written interfaces for the
generated ones.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsThUPqZXjwuuyRjBbmVkj

Author: 2 people

biome.json

@@ -33,6 +33,7 @@
       "!**/.venv",
       "!**/uploads",
       "!**/apps/sim/lib/execution/sandbox/bundles/*.cjs",
+      "!**/packages/sim-cli/src/generated",
       "!**/test-results",
       "!**/playwright-report"
     ]

package.json

@@ -50,6 +50,9 @@
     "check:audits": "bun run scripts/run-audits.ts",
     "check:desktop-bridge": "bun run scripts/check-desktop-bridge-contract.ts --check",
     "check:desktop-ipc": "bun run scripts/check-desktop-ipc-contract.ts",
+    "check:cli-api": "bun run scripts/generate-v2-cli-api.ts --check",
+    "check:openapi-drift": "bun run scripts/generate-v2-cli-api.ts --check-openapi",
+    "generate:cli-api": "bun run scripts/generate-v2-cli-api.ts",
     "desktop-bridge-contract:update": "bun run scripts/check-desktop-bridge-contract.ts --update",
     "mship-contracts:generate": "bun run scripts/sync-mothership-stream-contract.ts",
     "mship-contracts:check": "bun run scripts/sync-mothership-stream-contract.ts --check",

packages/sim-cli/README.md

@@ -114,6 +114,13 @@ sim logs list [--level error] [--workflow <id>…] [--trigger <name>…] [--star
 sim logs get <id>
 sim logs execution <executionId>
 
+sim tables list
+sim tables get <tableId>
+sim tables columns <tableId>
+sim tables rows <tableId> [--filter <json>] [--sort <field:dir>…] [--limit <n>]
+sim tables insert <tableId> --data <json>
+sim tables delete-rows <tableId> (--row <id>… | --filter <json>) --yes
+
 sim files list
 sim files download <fileId> [-o <path>]
 sim files delete <fileId>
@@ -124,18 +131,61 @@ sim knowledge documents <id> [--search <text>]
 sim knowledge search <query> --kb <id>…
 ```
 
+### Filtering table rows
+
+`--filter` takes the same predicate tree the API uses — `all` (AND) or `any`
+(OR) groups of `{field, op, value}` conditions, nestable. It's JSON because the
+grammar is a tree; there's no honest flag encoding for it.
+
+```bash
+sim tables rows tbl_123 \
+  --filter '{"all":[{"field":"status","op":"eq","value":"open"},
+                    {"field":"score","op":"gt","value":10}]}' \
+  --sort score:desc --limit 50
+```
+
+Row columns are discovered at runtime from the returned data, unioned across the
+page so a sparse row doesn't hide a column.
+
+Deletions require an explicit selector *and* `--yes`; there is no "delete
+everything" default.
+
 Every command takes `--output json` for scripting; the JSON is the API's own
 response shape, so it pipes cleanly into `jq`.
 
 ```bash
 sim logs list --level error --output json | jq -r '.[].executionId'
 ```
 
+## How this stays in sync with the API
+
+`src/generated/v2-api.ts` is generated from the Zod route contracts in
+`apps/sim/lib/api/contracts/v2/**` — the same contracts the routes validate
+against, so a shape that disagrees with them is a shape the server would reject.
+It holds every response/request type plus the operation table (method, path,
+path params) the client dispatches through.
+
+```bash
+bun run generate:cli-api      # regenerate after changing a contract
+bun run check:cli-api         # CI: fails if the generated file is stale
+bun run check:openapi-drift   # CI: fails if the docs and contracts disagree
+```
+
+The generated file contains only type declarations and one const — no imports —
+so the `packages/*` must not import `apps/*` boundary is preserved; the script
+does the crossing at build time.
+
+The OpenAPI documents under `apps/docs` are deliberately **not** generated. They
+carry ~1000 hand-written descriptions and ~400 examples that Zod schemas don't
+encode, so regenerating them would trade real documentation for mechanical
+accuracy. `check:openapi-drift` reconciles their *structure* against the
+contracts instead — every v2 path and method must exist on both sides — so the
+prose survives while drift still fails the build.
+
 ## Notes
 
 - Commands talk to the `/api/v2` surface, which returns `{ data }` and
   `{ data, nextCursor }`. List commands auto-page up to `--limit`.
-- `sim tables` is not here yet — the tables v2 surface is still changing.
 
 ## License
 

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

@@ -4,18 +4,11 @@ import { basename } from 'node:path'
 import chalk from 'chalk'
 import { Command } from 'commander'
 import { clientFrom } from '../context.js'
+import type { ListFilesResponse } from '../generated/v2-api.js'
 import { SimApiError } from '../http/client.js'
 import { bytes, type Column, printList, timestamp } from '../output/render.js'
 
-interface WorkspaceFile {
-  id: string
-  name: string
-  size: number
-  type: string
-  key: string
-  uploadedBy: string
-  uploadedAt: string
-}
+type WorkspaceFile = ListFilesResponse['data'][number]
 
 /**
  * Streams a fetch body to disk, honouring backpressure.

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

@@ -1,38 +1,15 @@
 import { Command } from 'commander'
 import { clientFrom } from '../context.js'
+import type {
+  ListKnowledgeBasesResponse,
+  ListKnowledgeDocumentsResponse,
+  SearchKnowledgeResponse,
+} from '../generated/v2-api.js'
 import { bytes, type Column, printList, printRecord, text, timestamp } from '../output/render.js'
 
-interface KnowledgeBase {
-  id: string
-  name: string
-  description: string | null
-  docCount: number
-  tokenCount: number
-  embeddingModel: string
-  createdAt: string | null
-  updatedAt: string | null
-}
-
-interface KnowledgeDocument {
-  id: string
-  knowledgeBaseId: string
-  filename: string
-  fileSize: number
-  mimeType: string
-  processingStatus: string
-  chunkCount: number
-  tokenCount: number
-  enabled: boolean
-  createdAt: string | null
-}
-
-interface SearchHit {
-  documentId: string
-  documentName: string | null
-  content: string
-  chunkIndex: number
-  similarity: number
-}
+type KnowledgeBase = ListKnowledgeBasesResponse['data'][number]
+type KnowledgeDocument = ListKnowledgeDocumentsResponse['data'][number]
+type SearchHit = SearchKnowledgeResponse['data']['results'][number]
 
 const BASE_COLUMNS: Column<KnowledgeBase>[] = [
   { header: 'id', value: (kb) => kb.id },

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

@@ -1,25 +1,12 @@
 import chalk from 'chalk'
 import { Command } from 'commander'
 import { clientFrom } from '../context.js'
+import type { GetExecutionResponse, GetLogResponse, ListLogsResponse } from '../generated/v2-api.js'
 import { type Column, duration, printList, printRecord, text, timestamp } from '../output/render.js'
 
-interface LogListItem {
-  id: string
-  workflowId: string | null
-  executionId: string
-  level: string
-  trigger: string
-  startedAt: string
-  endedAt: string | null
-  totalDurationMs: number | null
-  cost: { total: number } | null
-  workflow?: { id: string | null; name: string; deleted: boolean }
-}
-
-interface LogDetail extends LogListItem {
-  executionData: unknown
-  createdAt: string
-}
+type LogListItem = ListLogsResponse['data'][number]
+type LogDetail = GetLogResponse['data']
+type ExecutionDetail = GetExecutionResponse['data']
 
 function level(value: string): string {
   return value === 'error' ? chalk.red(value) : value
@@ -128,17 +115,9 @@ export function logsCommand(): Command {
     .description('Show the workflow state snapshot for an execution')
     .action(async (executionId: string, _options: unknown, command: Command) => {
       const { client, profile } = clientFrom(command)
-      const execution = await client.getData<{
-        executionId: string
-        workflowId: string | null
-        executionMetadata: {
-          trigger: string
-          startedAt: string
-          endedAt: string | null
-          totalDurationMs: number | null
-          cost: { total: number } | null
-        }
-      }>(`/api/v2/logs/executions/${executionId}`)
+      const execution = await client.getData<ExecutionDetail>(
+        `/api/v2/logs/executions/${executionId}`
+      )
 
       printRecord(
         profile.output,