WorkOS Migrations
A CLI tool for migrating from identity providers into WorkOS. Supports Auth0, AWS Cognito, Clerk, Firebase Auth, and custom CSV — moving users, organizations, memberships, roles + permissions, password hashes, and TOTP MFA factors, with SAML/OIDC SSO connections surfaced as handoff artifacts.
Quick Start
The fastest way to get started is with the interactive wizard:
export WORKOS_SECRET_KEY=sk_...
npx @workos/migrations wizardThe wizard walks you through provider selection, export/transform, validation, and import step by step.
Installation
Run directly with npx (no install needed):
npx @workos/migrations <command>Or via the WorkOS CLI:
npx workos migrations <command>Or install globally:
npm install -g @workos/migrations
workos-migrate <command>Commands
| Command | Description | | --------------------------- | ----------------------------------------------------------------------------- | | export <provider | Unified export — write a migration package from any source (see below) | | wizard | Interactive step-by-step migration wizard | | export-auth0 | Deprecated alias for export auth0 (removed in v4.0) | | export-cognito | Deprecated alias for export cognito (removed in v4.0) | | export-template | Export a blank CSV template (users, samlconnections, oidcconnections, etc.) | | merge-passwords | Merge Auth0 password hashes into the export CSV | | transform-clerk | Deprecated alias for export clerk (removed in v4.0) | | transform-firebase | Deprecated alias for export firebase (removed in v4.0) | | validate | Validate a CSV file before import | | import | Import users from CSV into WorkOS | | import-package | Import a migration package directory into WorkOS | | generate-package-template | Generate an empty migration package skeleton | | validate-package | Validate a migration package against the contract | | analyze | Analyze import errors and generate retry CSV | | enroll-totp | Enroll TOTP MFA factors for imported users | | process-role-definitions | Create roles and assign permissions in WorkOS |
Run npx @workos/migrations <command --help for full option details on any command.
Exporting (unified command)
Every source is exported through one verb that always writes a migration package: