Quick Start

Codemod CLI is currently released under the @next tag while in alpha. Core commands and schema may change as we gather feedback. Check the CLI reference for updates until we publish a stable @latest.

Initialize a new codemod project

npx codemod@next init my-codemod

This scaffolds a new codemod project in the my-codemod directory.

Publish your codemod

npx codemod@next publish my-codemod

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

Run your codemod

npx codemod@next workflow run -w my-codemod/workflow.yaml

This runs your local codemod workflow on your codebase.

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 (new) is accessible using the npx codemod@next command. The following commands and options are available:

`codemod@next workflow`

Manage and execute workflow YAMLs. workflow run Run a workflow.

npx codemod@next workflow run -w <workflow.yaml|directory> [--param key=value]

Local workflows vs. Registry packages:

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

-w, --workflow <PATH>

string

required

Path to workflow file or directory.

--param <KEY=VALUE>

string

Workflow parameters (format: key=value).

Examples

Running a local workflow:

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

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

# Run with parameters
npx codemod@next workflow run -w ./my-codemod --param version=latest --param target=src

Running a workflow from the registry:

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

# Run with parameters
npx codemod@next @codemod-com/my-test-pkg --param version=latest --param target=src

Explore available packages on Codemod Registry.

workflow resume Resume a paused workflow.

npx codemod@next 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@next 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@next workflow status -i <ID>

-i, --id <ID>

string

required

Workflow run ID.

workflow list List workflow runs.

npx codemod@next workflow list [-l <LIMIT>]

-l, --limit <LIMIT>

number

Number of workflow runs to show. (default: 10)

workflow cancel Cancel a workflow run.

npx codemod@next workflow cancel -i <ID>

-i, --id <ID>

string

required

Workflow run ID.

`codemod@next 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@next 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 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@next 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@next jssg test my-codemod.js --language javascript

jssg run Run a JS ast-grep (jssg) codemod.

npx codemod@next 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@next 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@next init`

Initialize a new workflow project.

npx codemod@next init [PATH] [options]

[PATH]

string

Project directory name.

--name <NAME>

string

Project name (defaults to directory name).

--project-type <PROJECT_TYPE>

string

Project type: shell, ast-grep-js, ast-grep-yaml.

--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@next 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@next logout`

Logout from a registry.

npx codemod@next logout [--registry <REGISTRY>] [--all]

--registry <REGISTRY>

string

Registry URL to logout from.

--all

boolean

Logout from all registries.

`codemod@next whoami`

Show current authentication status.

npx codemod@next whoami [--registry <REGISTRY>] [--detailed]

--registry <REGISTRY>

string

Registry URL to check.

--detailed

boolean

Show detailed information including token scopes.

`codemod@next publish`

Publish a workflow to a registry.

npx codemod@next 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@next 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@next login --api-key ${{ secrets.CODEMOD_API_KEY }}
      - name: Publish codemod
        run: npx codemod@next publish . --scope your-org --access public --tag ${{ github.sha }}

Examples

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

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

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

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

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

`codemod@next unpublish`

Remove a package or selected version from the registry.

npx codemod@next 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@next unpublish my-codemod --version 0.1.0 --dry-run

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

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

# Unpublish from a custom registry
npx codemod@next unpublish my-codemod --force --registry https://registry.example.com

`codemod@next search`

Search for packages in the registry.

npx codemod@next 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@next search react

Filter by language and category:

npx codemod@next search --language typescript --category migration

Get results in JSON format:

npx codemod@next search --format json next

`codemod@next cache`

Manage the local package cache for codemod packages. cache info Show cache information and statistics.

npx codemod@next cache info

cache list List cached packages.

npx codemod@next cache list [--detailed]

--detailed

boolean

Show package details.

cache clear Clear cache for a specific package, or all packages.

npx codemod@next 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@next 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@next workflow`

`codemod@next jssg`

`codemod@next init`

`codemod@next logout`

`codemod@next whoami`

`codemod@next publish`

`codemod@next unpublish`

`codemod@next search`

`codemod@next cache`

Quickstart

Codemod Platform

OSS & Community

Quick Links

Other Resources

​Quick Start

​Advanced Concepts

​CLI Command Reference

​codemod@next workflow

​codemod@next jssg

​codemod@next init

​codemod@next login

​codemod@next logout

​codemod@next whoami

​codemod@next publish

​codemod@next unpublish

​codemod@next search

​codemod@next cache

Quick Start

Advanced Concepts

CLI Command Reference

`codemod@next workflow`

`codemod@next jssg`

`codemod@next init`

`codemod@next login`

`codemod@next logout`

`codemod@next whoami`

`codemod@next publish`

`codemod@next unpublish`

`codemod@next search`

`codemod@next cache`