GeezerVison

High-level idea

Problem: Sim’s public API lacks a terminal-native client that can securely obtain a platform credential, preserve environment-specific defaults, and expose the v2 resource surface—including binary, multipart, and credential-connection workflows—as predictable shell commands.
Solution: This PR publishes the CLI as [email protected] with browser-approved key exchange, AWS-style profiles, generated v2 commands plus terminal-shaped adapters, structured output, and branch-mapped npm releases in a single Node-compatible bundle.

Implementation level

Primary level: CLI application and runtime, supported by public API authentication and credential contracts plus release infrastructure.

Chokepoint: buildGeneratedCommands() consumes the generated V2_OPERATIONS table plus the sparse, hand-authored CLI_CONTRACT diff and turns them into the Commander command tree registered by src/index.ts.

Contract → runtime

canonical v2 route contracts
          │
          ▼
scripts/generate-v2-cli-api.ts
          │
          ▼
generated V2_OPERATIONS ───── CLI_CONTRACT overrides
          │                             │
          └──────────────┬──────────────┘
                         ▼
              buildGeneratedCommands()
                         │
            arguments, flags, and actions
                         │
                         ▼
                Commander command tree

The runtime is implemented and active in this PR. At the current head, the generated manifest contains 139 API operations; the generic runtime exposes 123 JSON operations plus three command variants, producing 126 generated command actions across 13 top-level resource groups. An operation absent from CLI_CONTRACT still becomes a command—the contract only records exceptions such as friendlier names, aliases, confirmations, positional arguments, output columns, and deliberately hidden operations.

The protocol layer handles the cases that cannot be represented as one ordinary JSON request. It hides the low-level transfer/session operations and attaches 12 terminal-shaped commands for file download and upload, knowledge-document upload, table import, and combined resource/folder navigation. These adapters compose the same v2 operations; they do not override backend behavior.

Credential creation is similarly translated into three terminal-shaped commands. sim credentials connect <providerId> --name <displayName> and sim credentials reconnect <credentialId> print a short-lived OAuth authorization URL and expiry. sim credentials create <providerId> --name <displayName> --credentials <json|@file> discovers the service-account provider, validates its exact required fields locally, and submits the provider-shaped credentials without exposing every provider’s secret fields as unrelated flags. The low-level generated forms are hidden.

sim secrets set <name> --scope <scope> uses a masked TTY prompt by default, restores terminal state on completion or cancellation, and fails fast without a terminal. Scripts can pass --value <value> explicitly; help warns that direct values are visible to shell history. The API response remains metadata-only.

packages/sim-cli/
├── package.json                         [new] sim metadata, binary, bundled build
├── THIRD_PARTY_LICENSES                 [new] notices for bundled dependencies
├── src/index.ts                         [new] registers generated and adapted commands
├── src/generated/v2-api.ts              [new] generated operation and wire-type manifest
├── src/contract/commands.ts             [new] sparse human-authored CLI presentation diff
├── src/runtime/build.ts                 [new] contract interpreter and command-tree chokepoint
├── src/runtime/request.ts               [new] argv coercion and typed request assembly
├── src/runtime/execute.ts               [new] requests and cursor pagination
├── src/runtime/result.ts                [new] contract-driven result rendering
├── src/commands/credentials.ts          [new] OAuth links and service-account schema translation
├── src/commands/secrets.ts              [new] interactive and explicit secret entry
├── src/commands/protocol/               [new] 12 binary and multi-request adapters
├── src/terminal/secret-input.ts         [new] masked TTY input with state restoration
├── src/auth/device-flow.ts              [new] browser handoff and credential polling
├── src/config/profile.ts                [new] AWS-style profile resolution and storage
└── src/output/                          [new] table, JSON, YAML, and text rendering

scripts/generate-v2-cli-api.ts            [new] canonical contracts → import-free CLI manifest

apps/sim/
├── package.json                         [edit] private web workspace renamed to @sim/app
├── lib/api/contracts/cli-auth.ts         [edit] browser/terminal handoff contract
├── app/api/cli/auth/approve/route.ts     [edit] approval and platform-key minting
├── app/api/cli/auth/poll/route.ts        [edit] one-time terminal redemption
├── app/cli/auth/cli-auth-view.tsx        [edit] pairing and workspace-default consent
├── lib/api/contracts/v2/credentials.ts   [edit] provider, connection, and credential contracts
└── app/api/v2/credentials/               [edit] list, provider, connect, and disconnect routes

.github/workflows/publish-sim-cli.yml     [new] authenticated sim releases and Node 20 smoke test
scripts/check-import-specifiers.ts        [edit] one extensionless-import policy for the repository

Approval UI

┌──────────────────────────────────────────────┐
│ Connect your terminal                        │
│ Approve only if this code matches it.        │
│                                              │
│                 K7M2-P9XT                    │
│                                              │
│ Default workspace                            │
│ [ Workspace name                          ▾ ]│
│ Personal key; this workspace is the default. │
│                                              │
│                              [ Connect ]     │
└──────────────────────────────────────────────┘

• Invalid or expired requests fail before approval.
• Workspace loading disables approval.
• The browser records consent but never receives the redeemable API key.
• The terminal polls once, receives the key, and writes the selected workspace as its profile default.
• sim login confirms before replacing an existing profile; non-interactive callers must pass --yes.

Type of Change

• New feature
• Improvement
• Refactoring

Testing

• bun run lint
• bun run check:audits
• bun run apps/sim/scripts/check-block-registry.ts origin/staging
• bun run check:migrations
• bun run check:import-specifiers --verbose
• bun run check:cli-api
• bun run --filter sim type-check
• bun run --filter sim test — 242 passed, 1 skipped
• bun run --filter sim build
• Credential v2 route tests — 41 passed
• Packed artifact executes under Node 20.20.2
• git diff --check

Checklist

• Code follows repository conventions
• Tests cover the CLI runtime, profiles, authentication, output, protocol adapters, and credential connection links
• Generated API artifacts are synchronized with canonical contracts
• Published artifacts contain the executable bundle and third-party notices
• No database change remains in the PR