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

Command Relationships

The Codemod CLI provides different commands for different stages of development:

High-Level Commands (Production)

# Run a published package from the registry
npx codemod @org/my-package

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

Use for: Production codemods, multi-step workflows, parameterized transforms

Quick Testing Commands (Development)

# Test a jssg transform directly
npx codemod jssg run ./transform.ts ./src --language tsx

# Test jssg transform with fixtures
npx codemod jssg test ./transform.ts --language tsx

Use for: Rapid iteration, testing patterns, development

Package Lifecycle

# Scaffold a new package
npx codemod init

# Validate workflow
npx codemod workflow validate -w workflow.yaml

# Publish to registry
npx codemod publish

When to use what: Use codemod workflow run for orchestrated, multi-step transformations with parameters. Use codemod jssg run for quick testing of a single jssg transform during development.

CLI Command Reference

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

`codemod workflow`

Manage and execute Codemod packages. A Codemod package is a directory containing workflow.yaml and transformation scripts. Workflows orchestrate multiple steps using different engines (jssg, YAML ast-grep, shell commands, AI, etc.). When to use:

✅ Production codemods with multiple steps
✅ Parameterized transformations
✅ Multi-repo orchestration
✅ State management and resumption

Learn more: Building Workflows workflow run Run a complete 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.

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

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`

Run jssg (JS ast-grep) transforms directly without a workflow. jssg is the primary transformation engine for Codemod. These commands let you test jssg transforms quickly during development. When to use:

✅ Quick testing of a single transform
✅ Iterating on pattern matching
✅ Development and debugging

When NOT to use:

❌ Multi-step transformations → use codemod workflow
❌ Parameterized transforms → use codemod workflow with --param
❌ Production deployments → use codemod workflow for orchestration

For production, embed your jssg transform in a workflow using a js-ast-grep step. See Building Workflows: JS ast-grep step.

Learn more: jssg documentation

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?

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

Why ast-grep?

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.

More package types (advanced)

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.

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.

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.

Getting Started

Codemod Platform

OSS & Community

Other Resources

Codemod CLI

Quick Start

Command Relationships

High-Level Commands (Production)

Quick Testing Commands (Development)

Package Lifecycle

CLI Command Reference

`codemod workflow`

`codemod jssg`

`codemod init`

`codemod logout`

`codemod whoami`

`codemod publish`

`codemod unpublish`

`codemod search`

`codemod cache`

Getting Started

Codemod Platform

OSS & Community

Other Resources

​Quick Start

​Command Relationships

​High-Level Commands (Production)

​Quick Testing Commands (Development)

​Package Lifecycle

​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

Command Relationships

High-Level Commands (Production)

Quick Testing Commands (Development)

Package Lifecycle

CLI Command Reference

`codemod workflow`

`codemod jssg`

`codemod init`

`codemod login`

`codemod logout`

`codemod whoami`

`codemod publish`

`codemod unpublish`

`codemod search`

`codemod cache`