Codemod CLI

Scaffold, publish, and run codemod projects, recipes, or packages from your terminal using Codemod’s open-source CLI.

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.

---

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

Running a local workflow

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

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

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.

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]

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

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.