Quick Start

Initialize a new codemod project

npx codemod init

This scaffolds a new codemod project in the current directory.

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 workflow on your codebase to test it before publishing.

Publish your codemod

npx codemod publish

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

Run the published codemod

npx codemod @codemod-com/my-test-pkg

Run your published codemod directly from the Codemod Registry.

For more details on building and running workflows, see the Workflows documentation.

Advanced Concepts

Workflows: 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 workflow.

npx codemod workflow run -w <workflow.yaml|directory>

Local workflows vs. Registry packages:

Use npx codemod workflow run -w <path> for local workflow files and directories
Use npx codemod <package-name> to run packages directly from the Codemod Registry

-w, --workflow <PATH>

string

required

Path to workflow file or directory.

Examples

Running a local workflow:

# Run a local workflow file
npx codemod workflow run -w ./my-workflow.yaml

# Run a workflow from a local directory
npx codemod workflow run -w ./my-codemod


# Specify a target directory
npx codemod workflow run -w ./my-codemod -t /abs/path/to/repo

Running a workflow from the registry:

# Run a workflow package from the registry
npx codemod @codemod-com/my-test-pkg

# Specify a target directory
npx codemod @codemod-com/my-test-pkg -t /abs/path/to/repo

Explore available packages on Codemod Registry.

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.

Check	Ensures
Schema validation	YAML matches the workflow spec
Unique IDs	Node & template IDs are unique
Dependency validation	Every `depends_on` exists
Cyclic dependency detection	DAG has no cycles
Template references	All `template:` IDs exist
Matrix validation	`from_state` matches schema
State schema validation	`state.schema` is valid
Variable syntax	`${{…}}` uses `params`, `env`, `state`

Why validate?Validation catches issues before execution, saving time and preventing runtime errors.

Validation vs. Logical Correctness

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.

Write your codemod

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

Run your codemod

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

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 should I define a workflow instead?

Why ast-grep?

`codemod init`

Initialize a new workflow 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.

More package types (advanced)

--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.

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 workflow 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.

Publishing from CI (w/ GitHub App)

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

Publishing from CI (w/ API key)

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 }}

Examples

# 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]

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.

Examples

# 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

`codemod search`

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

Examples

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.

Quickstart

Codemod Platform

OSS & Community

Quick Links

Other Resources

Codemod CLI

Quick Start

Advanced Concepts

CLI Command Reference

`codemod workflow`

`codemod jssg`

`codemod init`

`codemod logout`

`codemod whoami`

`codemod publish`

`codemod unpublish`

`codemod search`

`codemod cache`

Quickstart

Codemod Platform

OSS & Community

Quick Links

Other Resources

​Quick Start

​Advanced Concepts

​CLI Command Reference

​codemod workflow

​codemod jssg

​codemod init

​codemod login

​codemod logout

​codemod whoami

​codemod publish

​codemod unpublish

​codemod search

​codemod cache

Quick Start

Advanced Concepts

CLI Command Reference

`codemod workflow`

`codemod jssg`

`codemod init`

`codemod login`

`codemod logout`

`codemod whoami`

`codemod publish`

`codemod unpublish`

`codemod search`

`codemod cache`