feat: Forward endpoint URL to migrations package

[jonatascastro12]

Summary

The workos migrations wrapper previously only forwarded WORKOS_SECRET_KEY to the migrations package. Users with custom endpoints (staging, self-hosted) had no way to direct migration API calls to their target environment.

Now runMigrations() accepts an optional apiBaseUrl param (resolved from the CLI's active environment via resolveApiBaseUrl()). When present, it sets WORKOS_API_URL in the process env before invoking the migrations CLI — the migrations package reads this env var to configure the SDK client's apiHostname.

-await runMigrations(passthrough, resolveOptionalApiKey({ apiKey: argv.apiKey }));
+await runMigrations(passthrough, resolveOptionalApiKey({ apiKey: argv.apiKey }), resolveApiBaseUrl());

Resolves https://linear.app/workos/issue/ENT-6103/fix-cli-gaps-found-in-200k-import-load-test

Link to Devin session: https://app.devin.ai/sessions/27dc2a764fe546458f3e28cf7f24bc28
Requested by: @jonatascastro12

[devin-ai-integration]

Original prompt from jonatas

Please work on ticket "Fix CLI gaps found in 200k import load test" (ENT-6103)

@playbook:playbook-b0d9a34380374c3e903d900d340d8da7

[devin-ai-integration]

🤖 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

[linear-code]

ENT-6103

[greptile-apps]

Greptile Summary

This PR forwards the active CLI environment's endpoint (if set) to the migrations package by passing it as WORKOS_API_URL in process.env. Users on staging or self-hosted endpoints can now run migrations against their target environment without manually exporting WORKOS_API_URL.

• bin.ts now reads getActiveEnvironment()?.endpoint (a string | undefined) and passes it as the third argument to runMigrations(), ensuring the env var is only set when a custom endpoint is actually configured.
• migrations.ts gains an optional apiBaseUrl parameter; the env var assignment is guarded by a truthiness check.
• New tests cover both the "set when provided" and "unset when absent" paths, and beforeEach correctly tears down WORKOS_API_URL between tests.

Confidence Score: 5/5

Safe to merge — the env var is set only when a custom endpoint is present, preserving existing shell-set values when no CLI environment endpoint is configured.

The call site correctly uses getActiveEnvironment()?.endpoint which returns undefined when no custom endpoint exists, so WORKOS_API_URL is never unconditionally overwritten. The function guard if (apiBaseUrl) is consistent with the existing WORKOS_SECRET_KEY pattern, tests cover both paths, and beforeEach teardown prevents cross-test pollution.

No files require special attention.

Important Files Changed

Filename	Overview
src/bin.ts	Switches from resolveApiBaseUrl() (always returns a string) to getActiveEnvironment()?.endpoint (returns undefined when no custom endpoint is configured), correctly passing undefined to runMigrations when appropriate.
src/commands/migrations.ts	Adds optional apiBaseUrl parameter; env var is only set when the value is truthy, consistent with the existing WORKOS_SECRET_KEY pattern.
src/commands/migrations.spec.ts	Adds WORKOS_API_URL cleanup in beforeEach and two new tests covering the set/unset cases; test coverage is adequate.

Sequence Diagram

sequenceDiagram
    participant User
    participant bin.ts
    participant config-store
    participant migrations.ts
    participant process.env
    participant migrations-pkg

    User->>bin.ts: workos migrations import --csv users.csv
    bin.ts->>config-store: getActiveEnvironment()
    config-store-->>bin.ts: "EnvironmentConfig | null"
    note over bin.ts: endpoint = env?.endpoint (string | undefined)
    bin.ts->>migrations.ts: runMigrations(args, apiKey, endpoint)
    migrations.ts->>process.env: "WORKOS_SECRET_KEY = apiKey (if set)"
    migrations.ts->>process.env: "WORKOS_API_URL = endpoint (only if truthy)"
    migrations.ts->>migrations-pkg: program.parseAsync(args)
    migrations-pkg->>process.env: reads WORKOS_SECRET_KEY, WORKOS_API_URL
    migrations-pkg-->>User: migration result

Loading

_{Reviews (2): Last reviewed commit: "fix: Only set WORKOS_API_URL for custom ..." | Re-trigger Greptile}