Codemod platform for semantic code transformations
npm install codemod



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.
``bash`
npm install -g codemod@latest
Or use via npx without installation:
`bash`
npx codemod@latest
`bash1. Create a codemod package
npx codemod init my-codemod
cd my-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
$3
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 filesPackages 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 →
$3
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).
`typescript
// 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 = (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.
$3
Workflows define how your codemod package runs. They can orchestrate multiple steps, handle dependencies, manage state, and even include manual approval gates:
`yaml
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
`CLI Commands
$3
| Command | Description |
|---------|-------------|
|
npx codemod init [path] | Create a new codemod package with interactive setup |
| npx codemod publish [path] | Publish package to the Codemod Registry |
| npx codemod login | Authenticate with the registry (browser or API key) |
| npx codemod logout | Logout from registry |
| npx codemod whoami | Show current authentication status |
| npx codemod search [query] | Search for packages in the registry |
| npx codemod unpublish | Remove a package from the registry |$3
| Command | Description |
|---------|-------------|
|
npx codemod workflow run -w | Run a codemod workflow on your codebase |
| npx codemod workflow validate -w | Validate workflow syntax and structure |
| npx codemod workflow resume -i | Resume a paused workflow |
| npx codemod workflow status -i | Show workflow execution status |
| npx codemod workflow list | List recent workflow runs |
| npx codemod workflow cancel -i | Cancel a running workflow |$3
| Command | Description |
|---------|-------------|
|
npx codemod jssg run | Run a jssg codemod directly |
| npx codemod jssg test | Test jssg codemod with fixtures |$3
| Command | Description |
|---------|-------------|
|
npx codemod cache info | Show cache statistics |
| npx codemod cache list | List all cached packages |
| npx codemod cache clear [package] | Clear cache for package or all |
| npx codemod cache prune` | Remove old or unused cache entries |For detailed options and examples, see the full CLI reference →
The Codemod CLI is part of a larger ecosystem designed to help teams modernize code at scale:
- 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
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 →
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.
MIT License - see LICENSE for details.
---
Built with ❤️ by Codemod and the open-source community