\n\n\n# Codemod CLI\n\n[](https://go.codemod.com/community)\n[](https://github.com/codemod/codemod/blob/main/LICENSE)\n[](https://www.npmjs.com/package/codemod)\n\n**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.\n\nWhether 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.\n\n## Installation\n\n```bash\nnpm install -g codemod\n```\n\nOr use via `npx` without installation:\n\n```bash\nnpx codemod\n```\n\nIn an interactive terminal, bare `npx codemod` opens a launcher and refreshes to the latest published CLI before showing the prompt. In non-interactive contexts, it prints next steps and exits with status `1`.\n\n## Quick Start\n\n```bash\n# 1. Start with the launcher or scaffold directly\nnpx codemod\n\n# 2. Create a codemod package\nnpx codemod init my-codemod\ncd my-codemod\n\n# You can create codemod packages with the help of AI using Codemod MCP or Studio\n\n# 3. Run it locally\nnpx codemod workflow run -w ./example-codemod -t /abs/path/to/repo\n\n# 4. Publish to registry\nnpx codemod login\nnpx codemod publish\n\n# 5. Run from registry\nnpx codemod @your-org/example-codemod\n```\n\n## What are Codemod Packages?\n\n**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:\n\n- **Transformation logic** – Written in JavaScript/TypeScript (jssg), YAML ast-grep rules, or shell scripts\n- **Workflow definition** – Orchestrates steps, handles dependencies, and manages execution\n- **Package manifest** – Defines metadata, target languages, and publishing configuration\n\nPackages are **fully portable**: run them locally during development, in CI/CD pipelines, or share them via the [Codemod Registry](https://go.codemod.com/registry) for your team or the community.\n\n## Why Codemod CLI?\n\n- **🎯 Built for Automation** – Scaffold, test, and publish codemod packages from your terminal\n- **📦 Registry Integration** – Share codemods via the [Codemod Registry](https://go.codemod.com/registry) or run community packages instantly\n- **⚡ Powerful Engines** – Leverage ast-grep (YAML + jssg) for fast, accurate AST-based transformations\n- **🤖 AI-Powered Creation** – Use [Codemod MCP](https://go.codemod.com/mcp-docs) in your IDE or [Codemod Studio](https://go.codemod.com/studio-docs) to build codemods with AI assistance\n- **🧪 Built-in Testing** – Validate codemods with snapshot testing before running on production code\n- **🔧 Flexible Runtime** – Run directly on your machine or in Docker/Podman containers\n\n## Core Concepts\n\n### Codemod Packages\n\nA **codemod package** is a directory containing:\n\n- `codemod.yaml` – Package metadata (name, version, description, target languages)\n- `workflow.yaml` – Workflow steps and orchestration logic\n- `scripts/` – JavaScript/TypeScript codemods (jssg)\n- `rules/` – YAML ast-grep rule files\n\nPackages 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.\n\n[Learn more about codemod packages →](https://docs.codemod.com/cli/packages)\n\n### jssg (JavaScript ast-grep)\n\n**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).\n\n```typescript\n// Example: Replace console.log with logger.info\nimport type { Codemod } from \"codemod:ast-grep\";\nimport type TSX from \"codemod:ast-grep/langs/tsx\";\n\nconst codemod: Codemod = (root) => {\n const rootNode = root.root();\n\n // Find all console.log calls\n const consoleCalls = rootNode.findAll({\n rule: { pattern: \"console.log($$$ARGS)\" }\n });\n\n if (consoleCalls.length === 0) {\n return null; // No changes needed\n }\n\n // Create edits\n const edits = consoleCalls.map((node) => {\n const args = node.getMatch('ARGS')?.text() || '';\n return node.replace(`logger.info(${args})`);\n });\n\n return rootNode.commitEdits(edits);\n};\n\nexport default codemod;\n```\n\njssg combines the power of AST transformations with the flexibility of JavaScript, making complex transformations intuitive and testable.\n\n[Learn more about jssg →](https://docs.codemod.com/jssg)\n\n### Workflow Orchestration\n\nWorkflows define how your codemod package runs. They can orchestrate multiple steps, handle dependencies, manage state, and even include manual approval gates:\n\n```yaml\nversion: \"1\"\nnodes:\n - id: transform\n name: Update API Calls\n type: automatic\n steps:\n - name: \"Run jssg codemod\"\n js-ast-grep:\n js_file: \"scripts/update-api.ts\"\n language: \"typescript\"\n include:\n - \"**/*.ts\"\n - \"**/*.tsx\"\n \n - name: \"Format code\"\n run: npx prettier --write \"**/*.{ts,tsx}\"\n \n - name: \"Run tests\"\n run: npm test\n```\n\n[Learn more about workflows →](https://docs.codemod.com/cli/packages/building-workflows)\n\n## CLI Commands\n\n### Package Management\n\n| Command | Description |\n|---------|-------------|\n| `npx codemod init [path]` | Create a new codemod package with interactive setup |\n| `npx codemod publish [path]` | Publish package to the Codemod Registry |\n| `npx codemod login` | Authenticate with the registry (browser or API key) |\n| `npx codemod logout` | Logout from registry |\n| `npx codemod whoami` | Show current authentication status |\n| `npx codemod search [query]` | Search for packages in the registry |\n| `npx codemod unpublish ` | Remove a package from the registry |\n\n### Workflow Commands\n\n| Command | Description |\n|---------|-------------|\n| `npx codemod workflow run -w ` | Run a codemod workflow on your codebase |\n| `npx codemod workflow validate -w ` | Validate workflow syntax and structure |\n| `npx codemod workflow resume -i ` | Resume a paused workflow |\n| `npx codemod workflow status -i ` | Show workflow execution status |\n| `npx codemod workflow list` | List recent workflow runs |\n| `npx codemod workflow cancel -i ` | Cancel a running workflow |\n\n### jssg Commands\n\n| Command | Description |\n|---------|-------------|\n| `npx codemod jssg run --language ` | Run a jssg codemod directly |\n| `npx codemod jssg test --language ` | Test jssg codemod with single-file or directory-snapshot fixtures |\n\n### Cache Management\n\n| Command | Description |\n|---------|-------------|\n| `npx codemod cache info` | Show cache statistics |\n| `npx codemod cache list` | List all cached packages |\n| `npx codemod cache clear [package]` | Clear cache for package or all |\n| `npx codemod cache prune` | Remove old or unused cache entries |\n\n**For detailed options and examples, see the [full CLI reference →](https://docs.codemod.com/cli/cli-reference)**\n\n## Ecosystem & Platform\n\nThe Codemod CLI is part of a larger ecosystem designed to help teams modernize code at scale:\n\n### Open-Source Tools\n\n- **[Codemod CLI](https://docs.codemod.com/cli)** (this package) – Build, test, and run codemod packages\n- **[Codemod MCP](https://go.codemod.com/mcp-docs)** – Build codemods with AI assistance in your IDE\n- **[Public Registry](https://go.codemod.com/registry)** – Discover and share community codemods\n\n### Enterprise Platform Features\n\nFor teams coordinating migrations across multiple repositories:\n\n- **[Codemod Studio](https://go.codemod.com/studio)** – AI-powered web interface for creating codemods\n- **[Campaigns](https://docs.codemod.com/migrations)** – Multi-repo orchestration with progress tracking\n- **[Insights](https://docs.codemod.com/insights)** – Analytics dashboards for measuring migration impact\n- **Private Registry** – Secure, organization-scoped codemod packages\n\n[Learn more about the platform →](https://app.codemod.com)\n\n## Resources\n\n### Documentation\n- **[Full Documentation](https://docs.codemod.com)** – Comprehensive guides and tutorials\n- **[CLI Reference](https://docs.codemod.com/cli/cli-reference)** – Detailed command documentation\n- **[Codemod Packages](https://docs.codemod.com/cli/packages)** – Learn more about codemod packages and workflows\n- **[jssg Documentation](https://docs.codemod.com/jssg)** – JavaScript ast-grep reference\n\n### Get Help\n- **[Slack Community](https://go.codemod.com/community)** – Ask questions and share codemods\n- **[GitHub Discussions](https://github.com/codemod/codemod/discussions)** – Long-form Q&A\n- **[GitHub Issues](https://github.com/codemod/codemod/issues)** – Report bugs or request features\n\n### Explore\n- **[Codemod Registry](https://go.codemod.com/registry)** – Browse community codemods\n- **[Codemod Studio](https://go.codemod.com/studio)** – Try creating codemods with AI\n- **[Example Codemods](https://github.com/codemod/codemod/tree/main/test-codemods)** – Reference implementations\n\n## Contributing\n\nContributions are welcome! Help make codemod automation better for everyone.\n\n**Ways to contribute:**\n- 🐛 Report bugs via [GitHub Issues](https://github.com/codemod/codemod/issues)\n- 💡 Suggest features on [Feedback Board](https://feedback.codemod.com)\n- 📝 Improve documentation\n- 🔧 Submit pull requests\n- 🌟 Star the repo and spread the word\n\nRead our [Contributing Guide](https://github.com/codemod/codemod/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/codemod/codemod/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nMIT License - see [LICENSE](https://github.com/codemod/codemod/blob/main/LICENSE) for details.\n\n---\n\n
![\"Codemod](\"https://raw.githubusercontent.com/codemod/codemod/main/apps/docs/images/intro/codemod-docs-hero-light.jpg\")
\n