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

Initialize a new codemod project

npx codemod@next init my-codemod
This scaffolds a new codemod project in the my-codemod directory.
2

Publish your codemod

npx codemod@next publish my-codemod
This publishes your codemod to the registry (you may need to login first).
3

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.
  • jssg: Run JavaScript/TypeScript codemods 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).
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.
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.
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

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

Write your codemod

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

Run your codemod

npx codemod@next 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@next jssg test my-codemod.js --language javascript
jssg run Run a jssg codemod.
npx codemod@next jssg run <codemod_file> <target_directory> [options]
codemod_file
string
required
Path to the 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 jssg codemod using before/after fixtures.
npx codemod@next jssg test <codemod_file> [options]
codemod_file
string
required
Path to the 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.

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.

codemod@next login

Login to a registry.
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.

codemod@next unpublish

Remove a package or selected version from the registry.
npx codemod@next 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.
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

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.