Skip to content

docs: Add migrations command to README#161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonatascastro12 merged 3 commits into from
May 29, 2026
Merged

docs: Add migrations command to README #161

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eb6477d
docs: Add migrations command to README
jonatascastro12 May 28, 2026
8d0ca10
docs: Fix import flag from --file to --csv
jonatascastro12 May 28, 2026
d4dce75
docs: Fix export-auth0 flags to use --client-id and --client-secret
jonatascastro12 May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -81,6 +81,9 @@ Resource Management:
api-key Manage per-org API keys
org-domain Manage organization domains

Migrations:
migrations Migrate users and SSO connections into WorkOS

Workflows:
seed Declarative resource provisioning from YAML
setup-org One-shot organization onboarding
Expand DownExpand Up@@ -196,6 +199,27 @@ Inspects a directory's sync state, user/group counts, recent events, and detects
workos debug-sync directory_01ABC123
```

### Migrations

Migrate users and SSO connections from other identity providers into WorkOS. The `migrations` namespace passes through to `@workos/migrations`.

```bash
# Interactive migration wizard
workos migrations wizard

# Export a blank CSV template
workos migrations export-template saml_connections --output saml_connections.csv
workos migrations export-template oidc_connections --output oidc_connections.csv

Comment on lines +210 to +213

@greptile-appsgreptile-appsBotMay 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1export-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-integrationdevin-ai-integrationBotMay 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

# Export from Auth0
workos migrations export-auth0 --domain your-tenant.auth0.com --client-id <id> --client-secret <secret>

# Import users from CSV
Comment on lines +216 to +217

@greptile-appsgreptile-appsBotMay 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1Incorrect 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-integrationdevin-ai-integrationBotMay 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

workos migrations import --csv users.csv
```

Run `workos migrations --help` for all available subcommands.

<!-- UNRELEASED: Local Development (emulator) — hidden until beta testing is complete.
To restore, uncomment this section and re-enable the `emulate` and `dev` commands
in src/bin.ts and src/utils/help-json.ts.
Expand Down
Loading