Registry / devops / schemashift-cli

schemashift-cli

library0.17.0jsnpmunverified

TypeScript schema migration CLI that converts between Zod, Yup, Joi, io-ts, Valibot, ArkType, Superstruct, and Effect Schema using AST-based transformations. Current stable version is 0.17.0, released monthly. Supports single-step and chain migrations, dry-run previews, compatibility checks, and integration testing scaffolding. Requires Node >=22.0.0. Differentiator: preserves comments and formatting via AST; includes behavioral difference warnings, bundle size estimation, and performance impact analysis.

devops

npm install schemashift-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SCHEMASHIFT-CLI

schemashift-cli

devopsjavascriptv0.17.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (binary)

✓ npx schemashift-cli <command>

✗ npm install -g schemashift && schemashift <command>

Package name is schemashift-cli, not schemashift. Install globally or use npx.

CLI usage

✓ schemashift migrate src/ -f yup -t zod

✗ schemashift --from yup --to zod src/

Position of path matters: path is first positional argument, options follow.

License file

✓ scheamsift license activate <key>

✗ npx schemashift license --activate <key>

Tier features require a license key. Free tier supports basic analyze and migrate.

Initialize configuration, analyze schemas, run a migration with dry-run, perform migration with git integration, and rollback using backup IDs.

# Initialize config npx schemashift-cli init --force # Analyze Zod schemas in src/ npx schemashift-cli analyze ./src --json --complexity # Migrate Yup to Zod with dry-run npx schemashift-cli migrate ./src -f yup -t zod -d -v # Perform migration with backup and git branch npx schemashift-cli migrate ./src -f yup -t zod --git-branch --git-commit --yes # Rollback if needed npx schemashift-cli rollback --list npx schemashift-cli rollback <backupId>

Debug

Known issues

breakingCLI binary was renamed from 'schemashift' to 'schemashift-cli' in v0.15.0. Running 'schemashift' will fail.

fix

Use `npx schemashift-cli` or reinstall with new package name.

affects: >=0.15.0

gotchaNode version requirement is >=22.0.0. Older Node versions will cause runtime errors.

fix

Upgrade Node.js to v22 or later, or use nvm to switch.

affects: >=0.17.0

deprecatedThe '--behavioral' flag in analyze command is deprecated since v0.16.0 and will be removed in v1.0.0.

fix

Use `--advisor` instead, which provides behavioral guidance plus migration advice.

affects: >=0.16.0

gotchaMigration from 'zod' without specifying version may incorrectly map v4 schemas. Use 'zod-v3' explicitly for Zod v3.

fix

Always specify source version: `-f zod-v3` for Zod v3, `-f zod` for v4.

affects: >=0.10.0

gotchaCross-file schema resolution requires '--cross-file' flag (Pro+ feature) and a license key. Without it, complex dependencies may be missed.

fix

Purchase a Pro+ license and activate with `schemashift-cli license activate <key>`, then add `--cross-file`.

affects: >=0.12.0

gotchaBackup creation is enabled by default. Use '--no-backup' to suppress. Backups can accumulate and bloat disk space.

fix

Run `schemashift-cli rollback --clean` periodically to remove old backups.

affects: >=0.8.0

gotchaMigration may produce incorrect output for deeply nested union/discriminated union types. Always review via dry-run first.

fix

Use `-d` flag to preview changes and verify manually before committing.

affects: 0.x

Errors

Common errors & fixes

Error: Cannot find module 'schemashift'

Using old binary name or package not installed as 'schemashift-cli'.

fix

Run `npm install -g schemashift-cli` and use `schemashift-cli` instead of `schemashift`.

Error: This feature requires a Pro+ license. Visit https://schemashift.dev/pricing to purchase.

Trying to use a feature that is not available in your current license tier.

fix

Purchase a license and activate it with `schemashift-cli license activate YOUR_KEY`.

TypeError: yup.date() resulted in a 'string' output instead of 'Date'

Behavioral difference: Yup's date() coerces strings, Zod's date() does not.

fix

Review migration output carefully; consider using `--advisor` to get warnings.

Error: Unsupported source type 'zod-v4'. Use '-f zod' for version 4 or '-f zod-v3' for version 3.

Invalid source library specifier.

fix

Use `-f zod` for Zod v4, `-f zod-v3` for Zod v3, or check docs for supported libraries.

Error: ENOENT: no such file or directory, open '.schemashiftrc.json'

Configuration file missing when required (e.g., when using chain migration or tier features).

fix

Run `schemashift-cli init` to create a configuration file, then retry.

Upgrade

Version history

0.17.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/jdmay2/schemashift ↗

packageschemashift-cli ↗

homepagehttps://schemashift.qwady.app ↗