Platform · Community · Docs

Codemod CLI

Codemod CLI is an open-source command-line tool for building, testing, and running codemod packages—automated code transformations that help teams modernize codebases, upgrade frameworks, and refactor at scale.

Whether you're an individual developer tackling tech debt, an OSS maintainer shipping upgrade paths, or a platform team coordinating migrations across hundreds of services, Codemod CLI gives you the tools to automate repetitive code changes reliably.

Installation

npm install -g codemod@latest

Or use via npx without installation:

npx codemod@latest <command>

Quick Start

# 1. Create a codemod package
npx codemod init my-codemod
cd my-codemod

# You can create codemod packages with the help of AI using Codemod MCP or Studio

# 2. Run it locally
npx codemod workflow run -w ./example-codemod -t /abs/path/to/repo

# 3. Publish to registry
npx codemod login
npx codemod publish

# 4. Run from registry
npx codemod @your-org/example-codemod

What are Codemod Packages?

Codemod packages are portable, reusable code transformation units that can range from simple find-and-replace operations to complex, multi-step migration workflows. Each package includes:

• Transformation logic – Written in JavaScript/TypeScript (jssg), YAML ast-grep rules, or shell scripts
• Workflow definition – Orchestrates steps, handles dependencies, and manages execution
• Package manifest – Defines metadata, target languages, and publishing configuration

Packages are fully portable: run them locally during development, in CI/CD pipelines, or share them via the Codemod Registry for your team or the community.

Why Codemod CLI?

• 🎯 Built for Automation – Scaffold, test, and publish codemod packages from your terminal
• 📦 Registry Integration – Share codemods via the Codemod Registry or run community packages instantly
• ⚡ Powerful Engines – Leverage ast-grep (YAML + jssg) for fast, accurate AST-based transformations
• 🤖 AI-Powered Creation – Use Codemod MCP in your IDE or Codemod Studio to build codemods with AI assistance
• 🧪 Built-in Testing – Validate codemods with snapshot testing before running on production code
• 🔧 Flexible Runtime – Run directly on your machine or in Docker/Podman containers

Core Concepts

Codemod Packages

A codemod package is a directory containing:

• codemod.yaml – Package metadata (name, version, description, target languages)
• workflow.yaml – Workflow steps and orchestration logic
• scripts/ – JavaScript/TypeScript codemods (jssg)
• rules/ – YAML ast-grep rule files

Packages can be as simple as a single transformation or as complex as multi-step migration workflows combining JavaScript codemods, YAML rules, shell scripts, and AI-assisted steps.

Learn more about codemod packages →

jssg (JavaScript ast-grep)

jssg enables you to write codemods in JavaScript/TypeScript that transform code in any language supported by ast-grep (JavaScript, TypeScript, Python, Rust, Go, Java, C++, and more).

// Example: Replace console.log with logger.info
import type { Transform } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";

const transform: Transform<TSX> = (root) => {
  const rootNode = root.root();

  // Find all console.log calls
  const consoleCalls = rootNode.findAll({
    rule: { pattern: "console.log($$$ARGS)" }
  });

  if (consoleCalls.length === 0) {
    return null; // No changes needed
  }

  // Create edits
  const edits = consoleCalls.map((node) => {
    const args = node.getMatch('ARGS')?.text() || '';
    return node.replace(`logger.info(${args})`);
  });

  return rootNode.commitEdits(edits);
};

export default transform;

jssg combines the power of AST transformations with the flexibility of JavaScript, making complex transformations intuitive and testable.

Learn more about jssg →

Workflow Orchestration

Workflows define how your codemod package runs. They can orchestrate multiple steps, handle dependencies, manage state, and even include manual approval gates:

version: "1"
nodes:
  - id: transform
    name: Update API Calls
    type: automatic
    steps:
      - name: "Run jssg codemod"
        js-ast-grep:
          js_file: "scripts/update-api.ts"
          language: "typescript"
          include:
            - "**/*.ts"
            - "**/*.tsx"
      
      - name: "Format code"
        run: npx prettier --write "**/*.{ts,tsx}"
      
      - name: "Run tests"
        run: npm test

Learn more about workflows →

CLI Commands

Package Management

Workflow Commands

jssg Commands

Cache Management

For detailed options and examples, see the full CLI reference →

Ecosystem & Platform

The Codemod CLI is part of a larger ecosystem designed to help teams modernize code at scale:

Open-Source Tools

• Codemod CLI (this package) – Build, test, and run codemod packages
• Codemod MCP – Build codemods with AI assistance in your IDE
• Public Registry – Discover and share community codemods

Enterprise Platform Features

For teams coordinating migrations across multiple repositories:

• Codemod Studio – AI-powered web interface for creating codemods
• Campaigns – Multi-repo orchestration with progress tracking
• Insights – Analytics dashboards for measuring migration impact
• Private Registry – Secure, organization-scoped codemod packages

Learn more about the platform →

Resources

Documentation

• Full Documentation – Comprehensive guides and tutorials
• CLI Reference – Detailed command documentation
• Codemod Packages – Learn more about codemod packages and workflows
• jssg Documentation – JavaScript ast-grep reference

Get Help

• Slack Community – Ask questions and share codemods
• GitHub Discussions – Long-form Q&A
• GitHub Issues – Report bugs or request features

Explore

• Codemod Registry – Browse community codemods
• Codemod Studio – Try creating codemods with AI
• Example Codemods – Reference implementations

Contributing

Contributions are welcome! Help make codemod automation better for everyone.

Ways to contribute:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features on Feedback Board
• 📝 Improve documentation
• 🔧 Submit pull requests
• 🌟 Star the repo and spread the word

Read our Contributing Guide and Code of Conduct.

License

MIT License - see LICENSE for details.

Built with ❤️ by Codemod and the open-source community