fix: Make migrations API key optional

[jonatascastro12]

Summary

• Add optional API key resolution for commands that can run without credentials.
• Stop resolving a required WorkOS API key before delegating to @workos/migrations.
• Only set WORKOS_SECRET_KEY for migrations when an API key is configured or passed.

Review & Testing Checklist for Human

• Verify npx workos migrations wizard opens the migration wizard without a configured WorkOS API key.
• Verify WorkOS-importing migration flows still receive WORKOS_SECRET_KEY when --api-key, WORKOS_API_KEY, or an active environment is configured.

Notes

Tested locally with:

• pnpm vitest run src/commands/migrations.spec.ts src/lib/api-key.spec.ts
• pnpm tsc --noEmit
• pnpm lint
• pnpm format:check
• pnpm build
• pnpm test
• env -u WORKOS_API_KEY HOME="/home/ubuntu/repos/cli/.devin-empty-home" timeout 3s ./dist/bin.js migrations wizard

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

---

Summary by CodeRabbit

• New Features

  • Migrations command now supports running without an explicit API key, allowing optional authentication.

• Behavior Changes

  • API key resolution now cleanly returns no value when none is provided and only sets credentials when an API key is supplied.

• Tests

  • Added tests covering migrations and API key resolution when no API key is present.

[devin-ai-integration]

Original prompt from jonatas

When running npx workos migrations wizard, I get:
No API key configured. Run workos env add to configure an environment, or set WORKOS_API_KEY.

Not all features in workos migrations require a WORKOS_API_KEY. We need to fix this in workos CLI.

[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 and CI monitoring

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 902e7591-9ba3-42d6-b438-8fdab0225eb9

📥 Commits

Reviewing files that changed from the base of the PR and between fd836de and eb66811.

📒 Files selected for processing (1)

• src/lib/api-key.spec.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/api-key.spec.ts

---

📝 Walkthrough

Walkthrough

The PR makes API key optional for the migrations CLI command. A new resolveOptionalApiKey function is introduced to resolve API keys without requiring an error exit. The existing resolveApiKey is refactored to delegate to it. The runMigrations function and migrations command handler are updated to accept and pass optional API keys.

Changes

Optional API key resolution for migrations

Layer / File(s)	Summary
Optional API key resolution helper src/lib/api-key.ts, src/lib/api-key.spec.ts	resolveOptionalApiKey is introduced to implement the resolution chain (options.apiKey → WORKOS_API_KEY → stored apiKey → undefined). resolveApiKey is refactored to delegate to this helper and only call exitWithError when no key is available. Tests verify the optional resolver returns undefined or a configured key and that error handling remains correct.
Migrations command with optional API key src/commands/migrations.ts, src/bin.ts, src/commands/migrations.spec.ts	runMigrations function signature becomes runMigrations(args: string[], apiKey?: string) and conditionally sets process.env.WORKOS_SECRET_KEY only when provided. The migrations command handler switches to resolveOptionalApiKey and passes the resolved optional key. A test confirms runMigrations works without an API key.

Possibly related PRs

• workos/cli#149: Both PRs modify the workos migrations wrapper's auth handling in src/commands/migrations.ts/src/bin.ts—specifically how runMigrations resolves/injects the API key and sets process.env.WORKOS_SECRET_KEY (required key in #149 vs optional/conditional in the main PR).
• workos/cli#137: Both PRs modify the API key resolution logic in src/lib/api-key.ts (introducing/using resolveOptionalApiKey in main, and changing resolveApiKey's precedence/behavior in retrieved), which directly impacts how migrations and other commands handle WORKOS_API_KEY vs provided keys.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly summarizes the main change: making the migrations API key optional rather than required.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/1778713127-optional-migrations-api-key

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[greptile-apps]

Greptile Summary

This PR makes the API key optional for the migrations command, allowing workos migrations wizard to run without any configured credentials while preserving key injection for import flows that need it.

• resolveOptionalApiKey is extracted from resolveApiKey in src/lib/api-key.ts; resolveApiKey now delegates to it and calls exitWithError only on the required path, keeping the never-typed return contract intact.
• runMigrations signature changes from apiKey: string to apiKey?: string, and WORKOS_SECRET_KEY is set conditionally — if no key is resolved, any pre-existing WORKOS_SECRET_KEY in the environment is left untouched.
• Four direct tests are added for resolveOptionalApiKey covering all resolution paths; the migrations spec adds an explicit no-key test with proper beforeEach cleanup.

Confidence Score: 5/5

Safe to merge — the change is narrowly scoped to making the API key optional for migrations, all existing required-key paths are unaffected, and both new and existing code paths have direct test coverage.

The refactor correctly extracts the optional resolution path from the mandatory one without touching any other command. exitWithError is typed never, so resolveApiKey's string return type remains sound. Test isolation in both spec files is properly handled by beforeEach/afterEach hooks. No logic regressions are visible on the required-key path.

No files require special attention.

Important Files Changed

Filename	Overview
src/lib/api-key.ts	Refactors resolveApiKey to delegate to new resolveOptionalApiKey; adds optional path that returns undefined instead of exiting. exitWithError is typed never so TypeScript is satisfied.
src/commands/migrations.ts	Makes apiKey parameter optional; conditionally sets WORKOS_SECRET_KEY only when a key is available, allowing the wizard subcommand to run unauthenticated.
src/bin.ts	Switches migrations command handler from resolveApiKey to resolveOptionalApiKey, propagating the optional key through to runMigrations.
src/commands/migrations.spec.ts	Adds test for the no-API-key path; beforeEach properly deletes WORKOS_SECRET_KEY ensuring test isolation.
src/lib/api-key.spec.ts	Adds four direct tests for resolveOptionalApiKey covering flag, env-var, stored-config, and no-key paths; test isolation is handled by the existing beforeEach/afterEach hooks.

_{Reviews (2): Last reviewed commit: "test: Cover optional API key resolution ..." | Re-trigger Greptile}

[devin-ai-integration]

Runtime testing results

Tested the built CLI locally with WORKOS_API_KEY and WORKOS_SECRET_KEY unset plus an isolated empty HOME, then ran ./dist/bin.js migrations wizard in a pseudo-terminal.

• Passed — No API-key gate before wizard startup: output did not contain No API key configured. Run \workos env add` to configure an environment, or set WORKOS_API_KEY.`
• Passed — Wizard starts without credentials: output contained WorkOS Migration Wizard, This wizard will guide you through migrating users to WorkOS., and Step 1: Select Provider.
• Passed — Process reaches interactive provider selection: command timed out with status 124 after showing Which identity provider are you migrating from?, which is expected because the wizard waited for input.
• Passed — CI after final test-coverage commit: 8 checks passed, 0 failed, 0 pending.

Evidence:

  WorkOS Migration Wizard

  This wizard will guide you through migrating users to WorkOS.

  Press Ctrl+C at any time to exit.

  Step 1: Select Provider

? Which identity provider are you migrating from? › - Use arrow-keys. Return to submit.
❯   Auth0
    Export via Management API, bcrypt passwords
    Clerk
    Firebase Auth
    AWS Cognito
    Custom CSV

Devin session: https://app.devin.ai/sessions/f4c9c2c328ff472fbc1ec993e28380ac