docs: Add migrations command to README

[jonatascastro12]

Summary

Adds the migrations command/namespace to the CLI README:

• Listed in the command overview under a new "Migrations" category
• New ### Migrations section with usage examples (wizard, export-template, export-auth0, import)

Review & Testing Checklist for Human

• Verify the listed subcommands match what workos migrations --help actually shows

Notes

Docs-only change — no code modified.

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

Summary by CodeRabbit

• Documentation
  • Documented new Migrations resource group in CLI resource management
  • Added migration guide for users and SSO connections (SAML/OIDC) into WorkOS
  • Included example workflows: interactive setup wizard, CSV template exports, Auth0 migration, and user CSV imports
  • Complete migration subcommands available via migrations --help

[devin-ai-integration]

Original prompt from jonatas

Can you check if the CLI can export the CSV template for Enterprise connections?

I couldn't find the command.

[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

[coderabbitai]

Warning

Review limit reached

@devin-ai-integration[bot], we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 34 minutes and 44 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b624d911-c15c-4f16-a1a3-8a5989accc9a

📥 Commits

Reviewing files that changed from the base of the PR and between eb6477d and d4dce75.

📒 Files selected for processing (1)

• README.md

📝 Walkthrough

Walkthrough

Adds documentation for a new Migrations resource group in the CLI Resource Management command list and a section describing migration workflows with example subcommands for wizard, template export, and user import.

Changes

Migrations Feature Documentation

Layer / File(s)	Summary
Migrations documentation README.md	README.md introduces the migrations namespace in the Resource Management command list and adds a dedicated Migrations section with descriptions and example commands for running migration wizards, exporting CSV templates from SAML/OIDC connections, exporting from Auth0, and importing users from CSV, with a pointer to workos migrations --help for all available subcommands.

Possibly related PRs

• workos/cli#149: Implements the workos migrations command and argument passthrough logic that this PR documents.

Suggested reviewers

• nicknski

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: Add migrations command to README' accurately and clearly describes the main change: adding documentation about the migrations command to the README file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/1780006056-add-migrations-to-readme

---

_{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 bugs or issues to report.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6c87283f-3955-45fb-b21b-a942b917b201

📥 Commits

Reviewing files that changed from the base of the PR and between 3deb4c0 and eb6477d.

📒 Files selected for processing (1)

• README.md

[greptile-apps]

Greptile Summary

This PR documents the migrations command namespace in the CLI README, covering the command overview entry and a new ### Migrations section with usage examples.

• Adds migrations to the Resource Management overview and introduces a dedicated section with examples for wizard, export-template, export-auth0 (with corrected --client-id/--client-secret flags), and import.
• Closes the docs gap for the passthrough to @workos/migrations; no code is modified.

Confidence Score: 5/5

Documentation-only change with no code modifications; safe to merge.

The change is limited to README additions. The export-auth0 flags were corrected in a prior commit, and the spec file confirms that wizard, import --csv, and export-auth0 --client-id/--client-secret are all exercised in tests. No runtime behavior is altered.

README.md — the export-template subcommand examples (lines 211-212) were previously flagged as potentially non-existent in @workos/migrations; worth a manual workos migrations --help check before merging.

Important Files Changed

Filename	Overview
README.md	Adds Migrations section to command overview and detailed usage examples for wizard, export-template, export-auth0, and import subcommands; export-auth0 flags were corrected to --client-id/--client-secret in a prior fix.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[workos migrations] --> B{Subcommand}
    B --> C[wizard]
    B --> D[export-template]
    B --> E[export-auth0]
    B --> F[import]
    D --> D1[saml_connections]
    D --> D2[oidc_connections]
    C --> G[workos/migrations passthrough]
    D --> G
    E --> G
    F --> G
    G --> H[WorkOS API via WORKOS_SECRET_KEY]

Loading

_{Reviews (2): Last reviewed commit: "docs: Fix export-auth0 flags to use --cl..." | Re-trigger Greptile}

[greptile-apps]

Incorrect flags for export-auth0

The --token flag does not match the actual @workos/migrations CLI. According to the official WorkOS docs and the @workos/migrations GitHub repo, export-auth0 requires --client-id and --client-secret (M2M app credentials), not --token. Using the documented command as-is will fail. The spec file (migrations.spec.ts line 40) also uses --client-id/--client-secret rather than --token, confirming the flag name is wrong.

[devin-ai-integration]

Good catch — fixed in the latest commit. Changed to --client-id <id> --client-secret <secret>.

[greptile-apps]

export-template is not a documented subcommand of @workos/migrations

The @workos/migrations package lists its subcommands as: wizard, export-auth0, export-cognito, merge-passwords, transform-clerk, transform-firebase, validate, import, import-package, analyze, enroll-totp, and process-role-definitions. export-template does not appear in that list, nor does it appear in the spec file. Running workos migrations export-template ... as documented would likely result in an unknown command error.

[devin-ai-integration]

export-template does exist — it was added in workos-migrations#90 (merged). See src/cli/commands/export-template.ts and src/cli/index.ts in the @workos/migrations repo. Greptile is likely looking at a stale snapshot of the codebase.