sim 2.2.7-preview.202.1 → 2.2.7

package/dist/index.js

@@ -9536,6 +9536,24 @@ var V2_OPERATIONS = {
     summary: "Activate Workflow Version",
     workspaceKeyUnsupported: true
   },
+  addOrganizationDomain: {
+    method: "POST",
+    path: "/api/v2/organizations/[organizationId]/domains",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "Add Organization Domain",
+    workspaceKeyUnsupported: true,
+    body: {
+      domain: {
+        kind: "string",
+        required: true,
+        describe: "Domain to claim and verify through a DNS TXT record."
+      }
+    }
+  },
   addPermissionGroupMember: {
     method: "POST",
     path: "/api/v2/organizations/[organizationId]/permission-groups/[groupId]/members",
@@ -11211,6 +11229,18 @@ var V2_OPERATIONS = {
       workspaceId: { kind: "string", required: true, describe: "Workspace that owns the skill." }
     }
   },
+  deleteSsoProvider: {
+    method: "DELETE",
+    path: "/api/v2/organizations/[organizationId]/sso/providers/[providerId]",
+    pathParams: ["organizationId", "providerId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed.",
+      providerId: "Identity provider identifier."
+    },
+    responseMode: "json",
+    summary: "Delete SSO Provider",
+    workspaceKeyUnsupported: true
+  },
   deleteTable: {
     method: "DELETE",
     path: "/api/v2/tables/[tableId]",
@@ -12383,6 +12413,29 @@ var V2_OPERATIONS = {
       workspaceId: { kind: "string", required: true, describe: "Workspace that owns the skill." }
     }
   },
+  getSsoPolicy: {
+    method: "GET",
+    path: "/api/v2/organizations/[organizationId]/sso/policy",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "Get SSO Policy",
+    workspaceKeyUnsupported: true
+  },
+  getSsoProvider: {
+    method: "GET",
+    path: "/api/v2/organizations/[organizationId]/sso/providers/[providerId]",
+    pathParams: ["organizationId", "providerId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed.",
+      providerId: "Identity provider identifier."
+    },
+    responseMode: "json",
+    summary: "Get SSO Provider",
+    workspaceKeyUnsupported: true
+  },
   getTable: {
     method: "GET",
     path: "/api/v2/tables/[tableId]",
@@ -12952,6 +13005,43 @@ var V2_OPERATIONS = {
       }
     }
   },
+  listCredentialMembers: {
+    method: "GET",
+    path: "/api/v2/credentials/[credentialId]/members",
+    pathParams: ["credentialId"],
+    pathParamDocs: { credentialId: "Credential whose sharing grants are managed." },
+    responseMode: "json",
+    summary: "List Credential Members",
+    workspaceKeyUnsupported: true,
+    query: {
+      workspaceId: {
+        kind: "string",
+        required: true,
+        describe: "Workspace expected to own the credential."
+      },
+      limit: {
+        kind: "integer",
+        default: 50,
+        describe: "Maximum credential members to return per page. Must be a whole number from 1 to 100. Defaults to 50."
+      },
+      cursor: {
+        kind: "string",
+        describe: "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor."
+      },
+      sortBy: {
+        kind: "enum",
+        values: ["email", "name"],
+        default: "email",
+        describe: "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order."
+      },
+      sortOrder: {
+        kind: "enum",
+        values: ["asc", "desc"],
+        default: "asc",
+        describe: "Sort direction."
+      }
+    }
+  },
   listCredentialProviders: {
     method: "GET",
     path: "/api/v2/credentials/providers",
@@ -13791,6 +13881,40 @@ var V2_OPERATIONS = {
       }
     }
   },
+  listOrganizationDomains: {
+    method: "GET",
+    path: "/api/v2/organizations/[organizationId]/domains",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "List Organization Domains",
+    workspaceKeyUnsupported: true,
+    query: {
+      limit: {
+        kind: "integer",
+        default: 50,
+        describe: "Maximum domain claims to return per page. Must be a whole number from 1 to 100. Defaults to 50."
+      },
+      cursor: {
+        kind: "string",
+        describe: "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor."
+      },
+      sortBy: {
+        kind: "enum",
+        values: ["domain"],
+        default: "domain",
+        describe: "Field used to sort the result."
+      },
+      sortOrder: {
+        kind: "enum",
+        values: ["asc", "desc"],
+        default: "asc",
+        describe: "Sort direction."
+      }
+    }
+  },
   listOrganizationInvitations: {
     method: "GET",
     path: "/api/v2/organizations/[organizationId]/invitations",
@@ -14410,6 +14534,40 @@ var V2_OPERATIONS = {
       }
     }
   },
+  listSsoProviders: {
+    method: "GET",
+    path: "/api/v2/organizations/[organizationId]/sso/providers",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "List SSO Providers",
+    workspaceKeyUnsupported: true,
+    query: {
+      limit: {
+        kind: "integer",
+        default: 50,
+        describe: "Maximum identity providers to return per page. Must be a whole number from 1 to 100. Defaults to 50."
+      },
+      cursor: {
+        kind: "string",
+        describe: "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor."
+      },
+      sortBy: {
+        kind: "enum",
+        values: ["providerId", "domain"],
+        default: "providerId",
+        describe: "Field used to sort the result."
+      },
+      sortOrder: {
+        kind: "enum",
+        values: ["asc", "desc"],
+        default: "asc",
+        describe: "Sort direction."
+      }
+    }
+  },
   listTableDispatches: {
     method: "GET",
     path: "/api/v2/tables/[tableId]/dispatches",
@@ -15389,6 +15547,37 @@ var V2_OPERATIONS = {
       }
     }
   },
+  removeCredentialMember: {
+    method: "DELETE",
+    path: "/api/v2/credentials/[credentialId]/members/[userId]",
+    pathParams: ["credentialId", "userId"],
+    pathParamDocs: {
+      credentialId: "Credential whose sharing grants are managed.",
+      userId: "User whose explicit grant will be revoked."
+    },
+    responseMode: "json",
+    summary: "Remove Credential Member",
+    workspaceKeyUnsupported: true,
+    query: {
+      workspaceId: {
+        kind: "string",
+        required: true,
+        describe: "Workspace expected to own the credential."
+      }
+    }
+  },
+  removeOrganizationDomain: {
+    method: "DELETE",
+    path: "/api/v2/organizations/[organizationId]/domains/[domainId]",
+    pathParams: ["organizationId", "domainId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed.",
+      domainId: "Domain claim owned by this organization."
+    },
+    responseMode: "json",
+    summary: "Remove Organization Domain",
+    workspaceKeyUnsupported: true
+  },
   removeOrganizationMember: {
     method: "DELETE",
     path: "/api/v2/organizations/[organizationId]/members/[userId]",
@@ -15801,6 +15990,258 @@ var V2_OPERATIONS = {
       workspaceId: { kind: "string", required: true, describe: "Unique workspace identifier." }
     }
   },
+  saveSsoProvider: {
+    method: "POST",
+    path: "/api/v2/organizations/[organizationId]/sso/providers",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "Save SSO Provider",
+    workspaceKeyUnsupported: true,
+    body: {
+      providerType: {
+        kind: "enum",
+        required: true,
+        values: ["oidc", "saml"],
+        describe: "oidc: Configure an OpenID Connect identity provider. saml: Configure a SAML identity provider."
+      },
+      providerId: {
+        kind: "string",
+        required: true,
+        describe: "Globally unique provider ID; saving an existing provider replaces its supplied configuration."
+      },
+      issuer: { kind: "string", required: true, describe: "Identity provider issuer URL." },
+      domain: {
+        kind: "string",
+        required: true,
+        describe: "Email domain already verified by this organization."
+      },
+      jitProvisioningEnabled: {
+        kind: "boolean",
+        default: true,
+        describe: "Allow SSO sign-in to provision organization membership, subject to eligibility and available seats."
+      },
+      mapping: {
+        kind: "object",
+        default: { id: "sub", email: "email", name: "name", image: "picture" },
+        describe: "Identity-provider claims mapped to user fields."
+      },
+      clientId: {
+        kind: "string",
+        describe: "Identity provider client identifier. Available when providerType is oidc. Required when providerType is oidc."
+      },
+      clientSecret: {
+        kind: "string",
+        describe: "Write-only client secret; the redacted marker from Get SSO Provider preserves an existing secret. Available when providerType is oidc. Required when providerType is oidc."
+      },
+      scopes: {
+        kind: "array",
+        default: ["openid", "profile", "email"],
+        describe: "OIDC scopes; offline_access is omitted. Available when providerType is oidc."
+      },
+      pkce: {
+        kind: "boolean",
+        default: true,
+        describe: "Use PKCE for the authorization flow. Available when providerType is oidc."
+      },
+      authorizationEndpoint: {
+        kind: "string",
+        describe: "Optional authorization endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc."
+      },
+      tokenEndpoint: {
+        kind: "string",
+        describe: "Optional token endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc."
+      },
+      userInfoEndpoint: {
+        kind: "string",
+        describe: "Optional UserInfo endpoint. Available when providerType is oidc."
+      },
+      skipUserInfoEndpoint: {
+        kind: "boolean",
+        default: false,
+        describe: "Read identity claims from the ID token instead of calling UserInfo. Available when providerType is oidc."
+      },
+      jwksEndpoint: {
+        kind: "string",
+        describe: "Optional signing-key endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc."
+      },
+      entryPoint: {
+        kind: "string",
+        describe: "Identity provider SAML sign-in endpoint. Available when providerType is saml. Required when providerType is saml."
+      },
+      cert: {
+        kind: "string",
+        describe: "Identity provider signing certificate. Available when providerType is saml. Required when providerType is saml."
+      },
+      callbackUrl: {
+        kind: "string",
+        describe: "SAML callback URL; defaults to this provider’s Sim callback. Available when providerType is saml."
+      },
+      audience: {
+        kind: "string",
+        describe: "SAML audience; omission preserves the saved value. Available when providerType is saml."
+      },
+      wantAssertionsSigned: {
+        kind: "boolean",
+        describe: "Require signed assertions; omission preserves the saved value. Available when providerType is saml."
+      },
+      signatureAlgorithm: {
+        kind: "string",
+        describe: "Signature algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml."
+      },
+      digestAlgorithm: {
+        kind: "string",
+        describe: "Digest algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml."
+      },
+      identifierFormat: {
+        kind: "string",
+        describe: "SAML NameID format; omission clears the saved value. Available when providerType is saml."
+      },
+      idpMetadata: {
+        kind: "string",
+        describe: "Identity provider metadata XML; omission clears the saved document. Available when providerType is saml."
+      }
+    },
+    bodyDiscriminator: {
+      field: "providerType",
+      variants: {
+        oidc: {
+          providerType: {
+            kind: "string",
+            required: true,
+            describe: "Configure an OpenID Connect identity provider."
+          },
+          providerId: {
+            kind: "string",
+            required: true,
+            describe: "Globally unique provider ID; saving an existing provider replaces its supplied configuration."
+          },
+          issuer: { kind: "string", required: true, describe: "Identity provider issuer URL." },
+          domain: {
+            kind: "string",
+            required: true,
+            describe: "Email domain already verified by this organization."
+          },
+          jitProvisioningEnabled: {
+            kind: "boolean",
+            default: true,
+            describe: "Allow SSO sign-in to provision organization membership, subject to eligibility and available seats."
+          },
+          mapping: {
+            kind: "object",
+            default: { id: "sub", email: "email", name: "name", image: "picture" },
+            describe: "Identity-provider claims mapped to user fields."
+          },
+          clientId: {
+            kind: "string",
+            required: true,
+            describe: "Identity provider client identifier."
+          },
+          clientSecret: {
+            kind: "string",
+            required: true,
+            describe: "Write-only client secret; the redacted marker from Get SSO Provider preserves an existing secret."
+          },
+          scopes: {
+            kind: "array",
+            default: ["openid", "profile", "email"],
+            describe: "OIDC scopes; offline_access is omitted."
+          },
+          pkce: {
+            kind: "boolean",
+            default: true,
+            describe: "Use PKCE for the authorization flow."
+          },
+          authorizationEndpoint: {
+            kind: "string",
+            describe: "Optional authorization endpoint; otherwise resolved through issuer discovery."
+          },
+          tokenEndpoint: {
+            kind: "string",
+            describe: "Optional token endpoint; otherwise resolved through issuer discovery."
+          },
+          userInfoEndpoint: { kind: "string", describe: "Optional UserInfo endpoint." },
+          skipUserInfoEndpoint: {
+            kind: "boolean",
+            default: false,
+            describe: "Read identity claims from the ID token instead of calling UserInfo."
+          },
+          jwksEndpoint: {
+            kind: "string",
+            describe: "Optional signing-key endpoint; otherwise resolved through issuer discovery."
+          }
+        },
+        saml: {
+          providerType: {
+            kind: "string",
+            required: true,
+            describe: "Configure a SAML identity provider."
+          },
+          providerId: {
+            kind: "string",
+            required: true,
+            describe: "Globally unique provider ID; saving an existing provider replaces its supplied configuration."
+          },
+          issuer: { kind: "string", required: true, describe: "Identity provider issuer URL." },
+          domain: {
+            kind: "string",
+            required: true,
+            describe: "Email domain already verified by this organization."
+          },
+          jitProvisioningEnabled: {
+            kind: "boolean",
+            default: true,
+            describe: "Allow SSO sign-in to provision organization membership, subject to eligibility and available seats."
+          },
+          mapping: {
+            kind: "object",
+            default: { id: "sub", email: "email", name: "name", image: "picture" },
+            describe: "Identity-provider claims mapped to user fields."
+          },
+          entryPoint: {
+            kind: "string",
+            required: true,
+            describe: "Identity provider SAML sign-in endpoint."
+          },
+          cert: {
+            kind: "string",
+            required: true,
+            describe: "Identity provider signing certificate."
+          },
+          callbackUrl: {
+            kind: "string",
+            describe: "SAML callback URL; defaults to this provider’s Sim callback."
+          },
+          audience: {
+            kind: "string",
+            describe: "SAML audience; omission preserves the saved value."
+          },
+          wantAssertionsSigned: {
+            kind: "boolean",
+            describe: "Require signed assertions; omission preserves the saved value."
+          },
+          signatureAlgorithm: {
+            kind: "string",
+            describe: "Signature algorithm accepted by the SAML configuration validator; omission preserves the saved value."
+          },
+          digestAlgorithm: {
+            kind: "string",
+            describe: "Digest algorithm accepted by the SAML configuration validator; omission preserves the saved value."
+          },
+          identifierFormat: {
+            kind: "string",
+            describe: "SAML NameID format; omission clears the saved value."
+          },
+          idpMetadata: {
+            kind: "string",
+            describe: "Identity provider metadata XML; omission clears the saved document."
+          }
+        }
+      }
+    }
+  },
   searchFileContent: {
     method: "GET",
     path: "/api/v2/files/search",
@@ -15912,6 +16353,18 @@ var V2_OPERATIONS = {
       sort: { kind: "array", describe: "Ordered table-row sort specification." }
     }
   },
+  setPrimarySsoProvider: {
+    method: "POST",
+    path: "/api/v2/organizations/[organizationId]/sso/providers/[providerId]/primary",
+    pathParams: ["organizationId", "providerId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed.",
+      providerId: "Identity provider identifier."
+    },
+    responseMode: "json",
+    summary: "Set Primary SSO Provider",
+    workspaceKeyUnsupported: true
+  },
   setSecret: {
     method: "PUT",
     path: "/api/v2/secrets/[name]",
@@ -16521,6 +16974,24 @@ var V2_OPERATIONS = {
       content: { kind: "string", describe: "Replacement skill body." }
     }
   },
+  updateSsoPolicy: {
+    method: "PATCH",
+    path: "/api/v2/organizations/[organizationId]/sso/policy",
+    pathParams: ["organizationId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed."
+    },
+    responseMode: "json",
+    summary: "Update SSO Policy",
+    workspaceKeyUnsupported: true,
+    body: {
+      requireSso: {
+        kind: "boolean",
+        required: true,
+        describe: "Require organization SSO on future sign-ins; existing sessions remain active."
+      }
+    }
+  },
   updateTable: {
     method: "PATCH",
     path: "/api/v2/tables/[tableId]",
@@ -16758,6 +17229,35 @@ var V2_OPERATIONS = {
       }
     }
   },
+  upsertCredentialMember: {
+    method: "POST",
+    path: "/api/v2/credentials/[credentialId]/members",
+    pathParams: ["credentialId"],
+    pathParamDocs: { credentialId: "Credential whose sharing grants are managed." },
+    responseMode: "json",
+    summary: "Upsert Credential Member",
+    workspaceKeyUnsupported: true,
+    query: {
+      workspaceId: {
+        kind: "string",
+        required: true,
+        describe: "Workspace expected to own the credential."
+      }
+    },
+    body: {
+      userId: {
+        kind: "string",
+        required: true,
+        describe: "Existing workspace member to grant or change access for."
+      },
+      role: {
+        kind: "enum",
+        required: true,
+        values: ["admin", "member"],
+        describe: "Credential role to grant; workspace administrators cannot be demoted."
+      }
+    }
+  },
   upsertFileShare: {
     method: "PATCH",
     path: "/api/v2/files/[fileId]/share",
@@ -16804,6 +17304,18 @@ var V2_OPERATIONS = {
       },
       conflictTarget: { kind: "string", describe: "Unique column used to detect a conflict." }
     }
+  },
+  verifyOrganizationDomain: {
+    method: "POST",
+    path: "/api/v2/organizations/[organizationId]/domains/[domainId]/verify",
+    pathParams: ["organizationId", "domainId"],
+    pathParamDocs: {
+      organizationId: "Organization whose single sign-on settings and verified domains are managed.",
+      domainId: "Domain claim owned by this organization."
+    },
+    responseMode: "json",
+    summary: "Verify Organization Domain",
+    workspaceKeyUnsupported: true
   }
 };
 
@@ -17760,6 +18272,24 @@ var CLI_CONTRACT = {
   deleteCredential: {
     confirm: "This disconnects the credential and removes its stored authentication."
   },
+  listCredentialMembers: {
+    columns: [
+      { header: "user", path: "userId" },
+      { header: "name", path: "userName" },
+      { header: "email", path: "userEmail" },
+      { header: "role" },
+      { header: "status" },
+      { header: "source", path: "roleSource" }
+    ]
+  },
+  upsertCredentialMember: {
+    command: "credentials members upsert",
+    flags: { userId: { name: "user" } }
+  },
+  removeCredentialMember: {
+    command: "credentials members remove",
+    confirm: "This revokes the selected user’s explicit credential grant."
+  },
   deleteSkill: { confirm: "This deletes the skill." },
   revokeSkillEditor: {
     confirm: "This revokes the explicit skill editor grant for the selected email."
@@ -18387,6 +18917,65 @@ var CLI_CONTRACT = {
     columns: [{ header: "id" }, { header: "name" }, { header: "role" }]
   },
   getOrganization: { command: "organizations get" },
+  listSsoProviders: {
+    command: "organizations sso providers list",
+    pathFlags: ORGANIZATION_FLAG,
+    columns: [
+      { header: "provider", path: "providerId" },
+      { header: "domain" },
+      { header: "primary", path: "isPrimary", format: "bool" },
+      { header: "verified", path: "domainVerified", format: "bool" }
+    ]
+  },
+  getSsoProvider: {
+    command: "organizations sso providers get",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  saveSsoProvider: {
+    command: "organizations sso providers save",
+    pathFlags: ORGANIZATION_FLAG,
+    flags: {
+      clientSecret: {
+        textSource: true,
+        describe: "Write-only OIDC client secret; the redacted marker from providers get preserves an existing secret. Passing it inline exposes it to shell history and process listings. Required when --provider-type is oidc"
+      }
+    }
+  },
+  deleteSsoProvider: {
+    command: "organizations sso providers delete",
+    pathFlags: ORGANIZATION_FLAG,
+    confirm: "This removes the identity provider used for SSO sign-in; linked accounts remain."
+  },
+  setPrimarySsoProvider: {
+    command: "organizations sso providers primary",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  getSsoPolicy: {
+    command: "organizations sso policy get",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  updateSsoPolicy: {
+    command: "organizations sso policy update",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  listOrganizationDomains: {
+    command: "organizations domains list",
+    pathFlags: ORGANIZATION_FLAG,
+    columns: [{ header: "id" }, { header: "domain" }, { header: "status" }]
+  },
+  addOrganizationDomain: {
+    command: "organizations domains add",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  verifyOrganizationDomain: {
+    command: "organizations domains verify",
+    pathFlags: ORGANIZATION_FLAG
+  },
+  removeOrganizationDomain: {
+    command: "organizations domains remove",
+    pathFlags: ORGANIZATION_FLAG,
+    confirm: "This removes the domain claim and revokes verified SSO authority for its providers."
+  },
   listOrganizationWorkspaces: {
     command: "organizations workspaces",
     pathFlags: ORGANIZATION_FLAG,
@@ -19928,6 +20517,9 @@ async function coerce(raw, field, flag, flagName) {
   }
   if (flag.rowCap)
     return coerceRowCap(raw, flagName);
+  if (flag.textSource && typeof raw === "string") {
+    return (await readArgumentSource(raw, flagName)).text;
+  }
   if (takesJson(field, flag)) {
     if (typeof raw !== "string")
       return raw;
@@ -20103,11 +20695,13 @@ var DEFAULT_PAGE_SIZE = 100;
 var COMPLETE_LIST_OPERATIONS = new Set([
   "listBlocks",
   "listChatDeployments",
+  "listCredentialMembers",
   "listCredentials",
   "listCustomTools",
   "listPermissionGroups",
   "listPermissionGroupMembers",
   "listOrganizations",
+  "listOrganizationDomains",
   "listOrganizationMembers",
   "listOrganizationWorkspaces",
   "listFiles",
@@ -20118,6 +20712,7 @@ var COMPLETE_LIST_OPERATIONS = new Set([
   "listSecrets",
   "listSkillEditors",
   "listSkills",
+  "listSsoProviders",
   "listTables",
   "listTools",
   "listWorkflowMcpServers",
@@ -20177,10 +20772,10 @@ function addFieldOption(command, operation, field, descriptor, slot, paginates,
   }
   const takesList = flag.list === true;
   const wantsJson = takesJson(descriptor, flag);
-  const placeholder = takesList ? "<value...>" : flag.rowCap ? "<n>" : wantsJson ? "<json|@file>" : descriptor.nullable ? "<number|null>" : "<value>";
+  const placeholder = takesList ? "<value...>" : flag.rowCap ? "<n>" : wantsJson ? "<json|@file>" : flag.textSource ? "<value|@file>" : descriptor.nullable ? "<number|null>" : "<value>";
   const choices = flag.choices ?? descriptor.values;
   const literalNull = slot === "body" && !takesList && !wantsJson && !descriptor.nullable;
-  const describe = `${documented}${takesList ? flag.manifest ? " (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @)" : " (space-separated, or @path / @- with one value per line; @@value for a literal leading @)" : wantsJson ? " (JSON, or @path / @- to read a file or stdin)" : ""}${descriptor.required ? " (required)" : ""}${literalNull ? literalNullHint(documented, name) : ""}`;
+  const describe = `${documented}${takesList ? flag.manifest ? " (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @)" : " (space-separated, or @path / @- with one value per line; @@value for a literal leading @)" : wantsJson ? " (JSON, or @path / @- to read a file or stdin)" : flag.textSource ? " (@path / @- reads a file or stdin verbatim, including trailing newlines; @@value for a literal leading @)" : ""}${descriptor.required ? " (required)" : ""}${literalNull ? literalNullHint(documented, name) : ""}`;
   const renamedFrom = flag.renamedFrom ?? [];
   const option = new Option(`${short}--${name} ${placeholder}`, describe);
   if (flag.hidden)