Skip to main content

​
Quick Start

1

Initialize a new codemod project

npx codemod init
This scaffolds a new codemod project in the current directory.
2

Run and test your codemod

cd /path/to/project-to-migrate

npx codemod workflow run -w /path/to/my-codemod/workflow.yaml
This runs your local codemod package on your codebase to test it before publishing.
3

Publish your codemod

npx codemod publish
This publishes your codemod to the registry (you may need to login first).
4

Run the published codemod

npx codemod @codemod/my-test-pkg
Run your published codemod directly from the Codemod Registry.
For more details on building and running codemod packages, see the Codemod Packages documentation.

​
Advanced Concepts

  • Codemod Packages: Orchestrate complex, multi-step codemod processes.
  • JS ast-grep (jssg): Run codemods written in JavaScript/TypeScript to transform code in any language using the high-performance ast-grep engine.

​
CLI Command Reference

Codemod CLI is accessible using the npx codemod command. The following commands and options are available:

​
codemod workflow

Manage and execute workflow YAMLs. workflow run Run a codemod package.
  • Use npx codemod workflow run -w <path> for local codemod packages and directories
  • Use npx codemod <package-name> to run packages directly from the Codemod Registry
npx codemod workflow run -w <workflow.yaml|directory>
​
-w, --workflow <PATH>
string
required
Path to workflow file or directory.
​
-t, --target <PATH>
string
Target directory to run the workflow on.
# Specify a target directory
npx codemod workflow run -w ./my-codemod -t /abs/path/to/repo

# Specify a target directory
npx codemod @codemod/my-test-pkg -t /abs/path/to/repo
​
--param <KEY=VALUE>
string
Pass key=value pairs to your workflow. Parameters are exposed to jssg transforms via options.params.
# Single parameter:
npx codemod workflow run -w workflow.yaml --param format=cjs

# Multiple parameters:
npx codemod workflow run -w workflow.yaml --param format=cjs --param strict=true
workflow resume Resume a paused workflow. 
npx codemod workflow resume -i <ID> [-t <TASK>] [--trigger-all]
​
-i, --id <ID>
string
required
Workflow run ID.
​
-t, --task <TASK>
string
Task ID to trigger (can be specified multiple times).
​
--trigger-all
boolean
Trigger all awaiting tasks.
workflow validate Validate a workflow file. 
npx codemod workflow validate -w <workflow.yaml>
​
-w, --workflow <FILE>
string
required
Path to workflow file.
CheckEnsures
Schema validationYAML matches the workflow spec
Unique IDsNode & template IDs are unique
Dependency validationEvery depends_on exists
Cyclic dependency detectionDAG has no cycles
Template referencesAll template: IDs exist
Matrix validationfrom_state matches schema
State schema validationstate.schema is valid
Variable syntax${{…}} uses params, env, state
Why validate?Validation catches issues before execution, saving time and preventing runtime errors.
The workflow validate command ensures your YAML is syntactically correct and follows the schema, but it cannot verify:
  • Logical correctness: Whether your workflow does what you intend
  • Runtime behavior: How your workflow behaves with real data
  • Dependencies: Whether external files/scripts exist
  • State consistency: Whether state updates are logically sound
workflow status Show workflow run status. 
npx codemod workflow status -i <ID>
​
-i, --id <ID>
string
required
Workflow run ID.
workflow list List workflow runs. 
npx codemod workflow list [-l <LIMIT>]
​
-l, --limit <LIMIT>
number
Number of workflow runs to show. (default: 10)
workflow cancel Cancel a workflow run. 
npx codemod workflow cancel -i <ID>
​
-i, --id <ID>
string
required
Workflow run ID.

​
codemod jssg

JS ast-grep (jssg) is a toolkit for running JavaScript/TypeScript codemods using the high-performance ast-grep engine. It enables fast, large-scale code transformations with a familiar API and robust language support. codemod jssg lets you run ast-grep codemods directly from the CLI, without needing to define a workflow. It’s built for speed and simplicity, making ast-grep codemods a first-class experience.
When should I use JS ast-grep (jssg)?
  • When you want to quickly run or test an ast-grep codemod on your codebase.
  • For more complex transformations that require granular AST access and manipulation than a YAML rule can provide. Read more about when to define workflows.
1

Write your codemod

Create a JS/TS file that exports your codemod logic.
2

Run your codemod

npx codemod jssg run my-codemod.js ./src --language javascript
3

Test your codemod

Organize your tests as follows:
tests/
├── simple-transform/
│   ├── input.js
│   └── expected.js
└── multi-file-case/
    ├── input/
    │   ├── file1.js
    │   └── file2.js
    └── expected/
        ├── file1.js
        └── file2.js
Then run:
npx codemod jssg test my-codemod.js --language javascript
jssg run Run a JS ast-grep (jssg) codemod. 
npx codemod jssg run <codemod_file> <target_directory> [options]
​
codemod_file
string
required
Path to the JS ast-grep (jssg) codemod file (JS/TS).
​
target_directory
string
required
Directory to apply the codemod to.
​
--language <LANG>
string
required
Target language (e.g., javascript, typescript, python, java, cpp, php, kotlin, etc.).
​
--extensions <ext1,ext2>
string
Comma-separated list of file extensions to process.
​
--no-gitignore
boolean
Do not respect .gitignore files.
​
--include-hidden
boolean
Include hidden files and directories in the scan.
​
--max-threads <N>
number
Maximum number of concurrent threads to use.
​
--dry-run
boolean
Perform a dry-run to see the changes without applying them.
jssg test Test a JS ast-grep(jssg) codemod using before/after fixtures. 
npx codemod jssg test <codemod_file> [options]
​
codemod_file
string
required
Path to the JS ast-grep (jssg) codemod file, which is a JS/TS file.
​
--language
string
required
Target language (e.g., javascript, typescript, python, java, cpp, php, kotlin, etc.).
​
--test-directory
string
The directory containing your tests (default: "tests").
​
--filter
string
A pattern to run only tests whose names match the filter.
​
--reporter
string
The output format for test results. Can be console, json, or terse.
​
--verbose
boolean
Show detailed output, including diffs for failed tests.
​
--context-lines
number
The number of context lines to show in diffs (default: 3).
​
--ignore-whitespace
boolean
Ignore whitespace differences when comparing test outputs.
​
--timeout
number
Test timeout in seconds (default: 30).
​
--max-threads
number
Maximum number of concurrent threads to use for running tests.
​
--sequential
boolean
Run tests sequentially instead of in parallel.
​
--fail-fast
boolean
Stop the test run on the first failure.
​
--update-snapshots, -u
boolean
Create or update the expected files with the output of the codemod. (-u is a shorthand for --update-snapshots)
​
--expect-errors
string
A comma-separated list of test patterns that are expected to fail.
​
--watch
boolean
Enable watch mode to automatically re-run tests when files change.
  • When you need to chain multiple codemods or scripts.
  • When you want manual review, approval steps, or CI/CD integration.
  • When you want to use engines other than ast-grep (e.g., jscodeshift, YAML, or custom scripts).
ast-grep is extremely fast and robust for syntax-aware code transformations. We made it first-class in the CLI for the most common use case, but you can still use any engine via workflows.jssg replicates the ast-grep NAPI, but with a few key differences:
  • It’s built into the CLI, so you can run it directly without needing to install it separately.
  • It’s built for speed and simplicity, making ast-grep codemods a first-class experience.

​
codemod init

Initialize a new codemod package project. 
npx codemod init [PATH] [options]
​
[PATH]
string
Project directory name.
​
--name <NAME>
string
Project name (defaults to directory name).
​
--project-type <PROJECT_TYPE>
string
Project type: ast-grep-js.
  • shell: Shell script-based codemods
  • ast-grep-yaml: YAML-based ast-grep codemods
​
--language <LANGUAGE>
string
Target language.
​
--description <DESCRIPTION>
string
Project description.
​
--author <AUTHOR>
string
Author name and email.
​
--license <LICENSE>
string
License.
​
--private
boolean
Make package private.
​
--force
boolean
Overwrite existing files.
​
--no-interactive
boolean
Use defaults without prompts.

​
codemod login

Login to a registry. 
npx codemod login [--api-key <API_KEY>] [--registry <REGISTRY>] [--scope <SCOPE>]
​
--api-key <API_KEY>
string
Authenticate using an API key. Skips the browser login & is ideal for CI.
​
--registry <REGISTRY>
string
Registry URL.
​
--scope <SCOPE>
string
Organization or user scope for publishing.
Need a key? Generate one in the Codemod app here ->.

​
codemod logout

Logout from a registry. 
npx codemod logout [--registry <REGISTRY>] [--all]
​
--registry <REGISTRY>
string
Registry URL to logout from.
​
--all
boolean
Logout from all registries.

​
codemod whoami

Show current authentication status. 
npx codemod whoami [--registry <REGISTRY>] [--detailed]
​
--registry <REGISTRY>
string
Registry URL to check.
​
--detailed
boolean
Show detailed information including token scopes.

​
codemod publish

Publish a codemod package to a registry. 
npx codemod publish [PATH] [options]
​
[PATH]
string
Path to codemod directory.
​
--version <VERSION>
string
Explicit version override.
​
--registry <REGISTRY>
string
Target registry URL.
​
--tag <TAG>
string
Tag for the release.
​
--access <ACCESS>
string
Access level (public, private).
​
--dry-run
boolean
Validate and pack without uploading.
Publishing from CI or on behalf of an organization? Install the Codemod GitHub App on the target repos.
Use this method when your organization has installed the Codemod GitHub App. The app injects CODEMOD_TOKEN automatically—no separate login step needed.
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Publish to Codemod Registry
        run: npx codemod publish . --scope your-org --access public --tag ${{ github.sha }}
        env:
          CODEMOD_TOKEN: ${{ secrets.CODEMOD_TOKEN }} # generated by GitHub App installation
Use this flow when the GitHub App isn’t installed. Requires login --api-key; works for publishing new versions of existing codemods (the first publish must be interactive).

Example action using a Codemod API key:
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Login to Codemod Registry with API key
        run: npx codemod login --api-key ${{ secrets.CODEMOD_API_KEY }}
      - name: Publish codemod
        run: npx codemod publish . --scope your-org --access public --tag ${{ github.sha }}

# Dry-run to verify bundle
npx codemod publish ./my-codemod --dry-run

# Publish a private package tagged beta
npx codemod publish ./my-codemod --access private --tag beta

# Override version and custom registry
npx codemod publish ./my-codemod --version 1.2.0 --registry https://registry.example.com

# Publish under an organization scope (requires GitHub App installation)
npx codemod publish ./my-codemod --scope nodejs

# After publishing, run your package from the registry
npx codemod @your-scope/my-codemod

​
codemod unpublish

Remove a package or selected version from the registry. 
npx codemod unpublish <PACKAGE> [options]
​
<PACKAGE>
string
required
Package name (e.g., @org/my-codemod or my-codemod).
​
--version <VERSION>
string
Specific semver to unpublish. Requires confirmation.
​
--force
boolean
Unpublish all versions (irreversible). Confirmation required.
​
--registry <REGISTRY>
string
Target registry URL.
​
--dry-run
boolean
Show what would be removed without actually unpublishing.
The CLI always prompts for confirmation when --version or --force is used. This interactive step cannot be bypassed programmatically.
# Preview removal of a single version
npx codemod unpublish my-codemod --version 0.1.0 --dry-run

# Remove a single version (will prompt)
npx codemod unpublish my-codemod --version 0.1.0

# Remove all versions (will prompt)
npx codemod unpublish my-codemod --force

# Unpublish from a custom registry
npx codemod unpublish my-codemod --force --registry https://registry.example.com
Search for packages in the registry. 
npx codemod search [OPTIONS] [QUERY]
​
[QUERY]
string
Search query
​
--language <LANGUAGE>
string
Filter by programming language
​
--framework <FRAMEWORK>
string
Filter by framework
​
--category <CATEGORY>
string
Filter by category
​
--size <SIZE>
number
Number of results to return (default: 20)
​
--from <FROM>
number
Pagination offset (default: 0)
​
--scope <SCOPE>
string
Filter by organization scope
​
--registry <REGISTRY>
string
Registry URL
​
--format <FORMAT>
string
Output format (default: table). Possible values: table, json, yaml
Search for codemods related to React:
npx codemod search react
Filter by language and category:
npx codemod search --language typescript --category migration
Get results in JSON format:
npx codemod search --format json next

​
codemod cache

Manage the local package cache for codemod packages. cache info Show cache information and statistics. 
npx codemod cache info
cache list List cached packages. 
npx codemod cache list [--detailed]
​
--detailed
boolean
Show package details.
cache clear Clear cache for a specific package, or all packages. 
npx codemod cache clear [PACKAGE] [--all]
​
[PACKAGE]
string
Package name (e.g., @org/package or package).
​
--all
boolean
Clear all cached packages.
cache prune Prune old or unused cache entries. 
npx codemod cache prune [--max-age <MAX_AGE>] [--dry-run]
​
--max-age <MAX_AGE>
number
Maximum age in days to keep (default: 30).
​
--dry-run
boolean
Dry run - show what would be removed.
⌘I