feat: add connection create and update commands by qbalin · Pull Request #221 · workos/cli

qbalin · 2026-08-14T17:38:10Z

Summary

Adds workos connection create and workos connection update <id> for provisioning and migrating SSO connections via the Connections API, plus a connections alias for the resource (kept out of metric fragmentation via command-aliases.ts).

Body assembly: --data '<json>' and --file <path|-> (stdin) provide the raw request body; top-level flags --org/--organization-id, --name, --external-id, --type override/merge on top. Nested saml_options / oidc_options / attribute_maps are passed through the raw JSON body. Non-object JSON bodies are rejected with invalid_json_body (type-narrowed via an isJsonObject guard — no casts).
workos-api.ts: add PATCH to WorkOSRequestOptions['method'] and send JSON bodies for PATCH.
workos-client.ts: new connections.create(body) / connections.update(id, body) raw methods.
connection create requires organization_id; connection update rejects an empty body. Both support human and --json output and reuse the standard API-key resolution and error handling.

These endpoints are feature-gated server-side (connections-api-migrations-capabilities-api) and return 404 unless enabled for the team.

Part of https://linear.app/workos/issue/ENT-6443 — companion docs PR in workos/workos.

Test plan

bun run typecheck, bun run lint, bun run format:check, bun run build — clean.
bun run vitest run src/commands/connection.spec.ts src/lib/workos-api.spec.ts — new specs cover request construction, flag/JSON precedence, --file/stdin parsing, invalid JSON, empty update body, API errors, and JSON output mode.

Link to Devin session: https://app.devin.ai/sessions/9151860048f44f5084cd0fe314e8722c
Requested by: @qbalin

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration · 2026-08-14T17:38:13Z

Original prompt from quentin.balin

Pick up this ticket. Ask any questions if need be: https://linear.app/workos/issue/ENT-6443/docs-cli-integration-workos-connections-create-update

linear-code · 2026-08-14T17:38:14Z

ENT-6443

devin-ai-integration · 2026-08-14T17:38:14Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

greptile-apps · 2026-08-14T17:41:38Z

Greptile Summary

The PR adds CLI commands for creating and updating SSO connections through the Connections API.

Registers connection create and connection update, with raw JSON/file input and top-level flag overrides.
Extends the API transport and client with PATCH-backed connection updates.
Adds the connections alias, static JSON help entries, documentation, and command/client tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/commands/connection.ts	Adds request-body parsing, validation, and handlers for connection creation and updates.
src/lib/workos-api.ts	Extends the shared API transport to accept PATCH and serialize PATCH request bodies.
src/lib/workos-client.ts	Adds raw Connections API methods for creating and updating SSO connections.
src/bin.ts	Registers the new subcommands and the plural connection alias.
src/utils/help-json.ts	Mirrors the new connection commands in the static machine-readable help catalog.

Sequence Diagram

sequenceDiagram
participant User
participant CLI as connection command
participant Client as workos-client
participant Transport as workosRequest
participant API as WorkOS Connections API
User->>CLI: create/update flags or JSON
CLI->>CLI: parse and merge request body
CLI->>Client: connections.create/update
Client->>Transport: POST/PATCH request options
Transport->>API: authenticated JSON request
API-->>Transport: connection response
Transport-->>CLI: parsed connection
CLI-->>User: human or JSON output

_{Reviews (3): Last reviewed commit: "fix: use success envelope for connection..." | Re-trigger Greptile}

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration

Devin Review found 2 potential issues.

devin-ai-integration · 2026-08-14T17:49:20Z

+ outputJson(connection);
+ return;
+ }
+ outputSuccess('Created connection', connection);
+ } catch (error) {


🟡 Machine-readable output for creating and updating connections omits the standard success wrapper
The newly created/updated connection is printed as a bare object (outputJson(connection) at src/commands/connection.ts:177-181) instead of the standard success envelope every other create/update command emits, so scripts and agents that read the status field get nothing back.
Impact: Automated callers parsing JSON output of these two commands see a different shape than for all other resource create/update commands and can mis-handle the result.
Why this deviates from the established output convention
CLAUDE.md requires new resource commands to follow the patterns in src/commands/organization.ts. There, create/update call outputSuccess('Created organization', org) (src/commands/organization.ts:34, src/commands/organization.ts:56), which in JSON mode produces { status: 'ok', message, data } (src/utils/output.ts:66-85). The same convention is used by role.ts (src/commands/role.ts:87, src/commands/role.ts:116) and by runConnectionDelete in this very file (src/commands/connection.ts:257). The new runConnectionCreate/runConnectionUpdate instead short-circuit with isJsonMode() + raw outputJson, matching only the get convention. Removing the isJsonMode() branch and calling outputSuccess alone yields both human and JSON output consistently (the new specs at src/commands/connection.spec.ts:288-302 would need to read output.data).
Suggested change
outputJson(connection);
return;
}
outputSuccess('Created connection',connection);
}catch(error){
outputSuccess('Created connection',connection);
Was this helpful? React with 👍 or 👎 to provide feedback.

Fixed in 588ce9b — create/update now call outputSuccess(...) unconditionally, so JSON mode emits the standard { status: 'ok', message, data } envelope like the other resource create/update commands, and the specs assert on output.status/output.data.

devin-ai-integration · 2026-08-14T17:49:21Z

+ connections: {
+ async create(body: Record<string, unknown>) {
+ return workosRequest<SsoConnection>({
+ method: 'POST',
+ path: '/connections',
+ apiKey: key,
+ baseUrl: base,
+ body,
+ });
+ },
+ async update(id: string, body: Record<string, unknown>) {
+ return workosRequest<SsoConnection>({
+ method: 'PATCH',
+ path: `/connections/${encodeURIComponent(id)}`,
+ apiKey: key,
+ baseUrl: base,
+ body,
+ });
+ },


🔍 create/update return snake_case while get returns camelCase
connections.create/connections.update use the raw fetch wrapper and therefore return the API's snake_case shape (SsoConnection at src/lib/workos-client.ts:30-41), whereas runConnectionGet and runConnectionList return SDK-mapped camelCase objects (src/commands/connection.ts:220, src/commands/connection.ts:48-56). Consumers of --json output will see connection_type/organization_id from create/update but type/organizationId from get/list on the same resource. Worth confirming this is acceptable for agent tooling, or normalizing the raw response before printing.
Was this helpful? React with 👍 or 👎 to provide feedback.

Accurate observation. This is deliberate: the pinned @workos-inc/node (8.13.0) has no createConnection/updateConnection, so these go through the raw transport, and I kept the API's snake_case shape in the output rather than hand-rolling a camelCase mapping. It's also symmetric with the input — --data/--file bodies are authored in the API's snake_case shape (matching the API reference docs), so the response echoes the same field names. If the SDK later ships these methods, switching to it would align create/update with get/list automatically. Happy to normalize now instead if consistency across subcommands matters more for agent tooling.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

feat: add connection create and update commands
7c387f1
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

qbalin self-assigned this Aug 14, 2026

This comment was marked as resolved.
Sign in to view

test: add transport-level coverage for connections client requests
3158c97
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integrationBot reviewed Aug 14, 2026
View reviewed changes

qbalin requested a review from jonatascastro12 August 14, 2026 17:55

fix: use success envelope for connection create/update JSON output
588ce9b
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Navigation Menu

Uh oh!

feat: add connection create and update commands - #221

feat: add connection create and update commands#221
qbalin wants to merge 3 commits into
mainfrom
devin/ent-6443-connection-create-update

qbalin commented Aug 14, 2026

Uh oh!

devin-ai-integrationBot commented Aug 14, 2026

Uh oh!

linear-codeBot commented Aug 14, 2026

Uh oh!

devin-ai-integrationBot commented Aug 14, 2026

Uh oh!

greptile-appsBot commented Aug 14, 2026•
edited
Loading

Sequence Diagram

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integrationBot left a comment

Uh oh!

devin-ai-integrationBotAug 14, 2026

Uh oh!

devin-ai-integrationBotAug 14, 2026

Uh oh!

devin-ai-integrationBotAug 14, 2026

Uh oh!

devin-ai-integrationBotAug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

-outputJson(connection);
-return;
-}
-outputSuccess('Created connection',connection);
-}catch(error){
+outputSuccess('Created connection',connection);

Uh oh!

Conversation

qbalin commented Aug 14, 2026

Summary

Test plan

Uh oh!

devin-ai-integrationBot commented Aug 14, 2026

Uh oh!

linear-codeBot commented Aug 14, 2026

Uh oh!

devin-ai-integrationBot commented Aug 14, 2026

🤖 Devin AI Engineer

Uh oh!

greptile-appsBot commented Aug 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integrationBot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integrationBotAug 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integrationBotAug 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integrationBotAug 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integrationBotAug 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

greptile-appsBot commented Aug 14, 2026•
edited
Loading