schemashift-cli

TypeScript schema migration CLI. Convert between Zod, Yup, Joi, io-ts, Valibot, ArkType, Superstruct, and Effect Schema with AST-based transformations.

Install

npm install -g schemashift-cli

Commands

init

Create a .schemashiftrc.json configuration file.

schemashift init [--force]

analyze

Analyze schemas in your project without modifying files.

schemashift analyze <path> [options]

| Option | Description | Tier | |--------|-------------|------| | --json | Output as JSON | Free | | -v, --verbose | Show detailed file paths | Free | | --detailed | Full stats with complexity scoring | Individual+ | | --readiness <path> | Migration readiness report, e.g. yup->zod | Individual+ | | --complexity | Per-schema complexity scores | Individual+ | | --behavioral <migration> | Behavioral difference warnings, e.g. yup->zod | Free | | --bundle <migration> | Bundle size estimation, e.g. zod->valibot | Individual+ | | --performance <migration> | Performance impact analysis, e.g. zod-v3->v4 | Individual+ | | --dedup | Detect duplicate type definitions | Individual+ | | --dead-schemas | Detect unused schema definitions | Individual+ | | --import-dedup | Detect duplicate imports from the same module | Individual+ | | --advisor <migration> | Migration vs Standard Schema adapter guidance | Free |

migrate

Transform schemas from one library to another.

schemashift migrate <path> [options]

Required (single-step):

| Option | Description | |--------|-------------| | -f, --from <library> | Source library (yup, joi, io-ts, zod-v3, zod) | | -t, --to <library> | Target library (zod, v4, valibot) |

Or (chain migration):

| Option | Description | Tier | |--------|-------------|------| | --chain <path> | Multi-step, e.g. yup->zod->valibot | Pro+ |

Options:

| Option | Description | Tier | |--------|-------------|------| | -d, --dry-run | Preview changes with diff output | Free | | -v, --verbose | Show warnings and detailed info | Free | | -c, --config <path> | Path to config file | Free | | --report <format> | Generate report (json, html, csv) | Individual+ | | --report-output <path> | Custom report output path | Individual+ | | --git-branch | Create a git branch for changes | Individual+ | | --git-commit | Auto-commit changes | Individual+ | | --no-backup | Skip backup creation | Free | | --yes | Skip confirmation prompt | Free | | --ci | CI mode (non-interactive, exit 1 on failure) | Pro+ | | --cross-file | Resolve cross-file schema dependencies | Pro+ | | --compat-check | Run compatibility check before migration | Pro+ | | --fail-on-warnings | Exit 1 if any warnings | Team | | --max-risk-score <n> | Exit 1 if any file exceeds risk score | Team | | --scaffold-tests | Generate validation tests after migration | Pro+ | | --audit | Enable migration audit logging | Team |

watch

Watch files and transform on save.

schemashift watch <path> -f <library> -t <library> [-c <config>]

Tier: Pro+

rollback

Restore files from a backup.

schemashift rollback [backupId]

| Option | Description | |--------|-------------| | -l, --list | List available backups | | --clean | Remove old backups (keeps last 5) |

license

Manage your license.

schemashift license [options]

| Option | Description | |--------|-------------| | -a, --activate <key> | Activate a license key | | -d, --deactivate | Deactivate current license | | -s, --status | Show license status |

compat

Check schema library compatibility before migration.

schemashift compat <path> [--json]

Detects installed library versions, reports version-specific issues, and identifies ecosystem dependencies (drizzle-zod, tRPC, etc.) affected by your migration.

Tier: Pro+

governance

Run schema governance checks.

schemashift governance <path> [--json] [-c <config>]

Enforces naming conventions, complexity limits, required validations, and more. Configure rules in .schemashiftrc.json.

Tier: Team

pricing

Display pricing information.

schemashift pricing

Configuration

Create .schemashiftrc.json with schemashift init:

{
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/*.d.ts"],
  "git": {
    "enabled": false,
    "createBranch": true,
    "branchPrefix": "schemashift/",
    "autoCommit": false
  },
  "backup": { "enabled": true, "dir": ".schemashift-backup" },
  "customRules": [],
  "suppressWarnings": [],
  "governance": {
    "rules": {
      "naming-convention": { "pattern": ".*Schema$" },
      "max-complexity": { "threshold": 80 },
      "no-any": {},
      "required-validations": {}
    }
  },
  "plugins": ["./my-plugin.js"]
}

Examples

# Quick analysis
schemashift analyze ./src

# Preview Yup→Zod migration
schemashift migrate ./src --from yup --to zod --dry-run

# Full migration with HTML report
schemashift migrate ./src --from yup --to zod --report html

# Zod v3→v4 upgrade with compatibility check
schemashift migrate ./src --from zod-v3 --to v4 --compat-check

# Chain migration: Yup→Zod→Valibot
schemashift migrate ./src --chain yup->zod->valibot

# CI mode
schemashift migrate ./src --from yup --to zod --ci --report json

# Backward migration: Zod→Yup
schemashift migrate ./src --from zod --to yup

# Backward migration: Valibot→Zod
schemashift migrate ./src --from valibot --to zod

# Analyze with behavioral warnings and bundle estimation
schemashift analyze ./src --behavioral yup->zod --bundle yup->zod

# Get adapter-vs-migration guidance
schemashift analyze ./src --advisor zod->valibot

# Migrate with test scaffolding
schemashift migrate ./src --from yup --to zod --scaffold-tests

# Rollback last migration
schemashift rollback

Environment Variables

| Variable | Description | |----------|-------------| | SCHEMASHIFT_LICENSE_KEY | License key for CI/CD (avoids interactive activation) |

Related Packages

| Package | Description | |---------|-------------| | @schemashift/core | Core analysis and transformation engine | | @schemashift/yup-zod | Yup ↔ Zod transformer | | @schemashift/joi-zod | Joi → Zod transformer | | @schemashift/zod-v3-v4 | Zod v3 → v4 upgrade | | @schemashift/io-ts-zod | io-ts → Zod transformer | | @schemashift/zod-valibot | Zod ↔ Valibot transformer | | @schemashift/zod-arktype | Zod ↔ ArkType transformer | | @schemashift/zod-superstruct | Zod ↔ Superstruct transformer | | @schemashift/io-ts-effect | io-ts → Effect Schema transformer |

Links

• Documentation
• Pricing
• Migration Guides

License

MIT