Codemod CLI

Go to:

Codemod CLI is released under the temporary @next tag while it’s in alpha. The core commands and workflow schema may change as we gather feedback. Please keep an eye on the CLI reference until we publish a stable @latest.

Codemod CLI (new) is accessible using the npx codemod@next command. The following commands and options are available:

workflow — Manage workflows (see subcommands below)
jssg — JavaScript ast-grep execution (see subcommands below)
init — Initialize a new workflow project
login — Login to a registry
logout — Logout from a registry
whoami — Show current authentication status
publish — Publish a workflow
search — Search for packages in the registry
run — Run a codemod from the registry
cache — Manage package cache (see subcommands below)

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

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

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`

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.

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

Quick Start Example

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

Testing Framework

Advanced Usage & Best Practices

`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 [--registry <REGISTRY>] [--scope <SCOPE>]

--registry <REGISTRY>

string

Registry URL.

--scope <SCOPE>

string

Organization or user scope for publishing.

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

`codemod@next search`

Search for packages in the registry.

npx codemod@next search [QUERY] [options]

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

Codemod Platform

Quickstart

Codemod Platform

OSS & Community

Quick Links

Other Resources

Go to:

`codemod@next workflow`

`workflow run`

`workflow resume`

`workflow validate`

`workflow status`

`workflow list`

`workflow cancel`

`codemod@next jssg`

`jssg run`

`jssg test`

`codemod@next init`

`codemod@next logout`

`codemod@next whoami`

`codemod@next publish`

`codemod@next search`

`codemod@next cache`

`cache info`

`cache list`

`cache clear`

`cache prune`

Go to:

Quickstart

Codemod Platform

OSS & Community

Quick Links

Other Resources

Go to:

​codemod@next workflow

​workflow run

​workflow resume

​workflow validate

​workflow status

​workflow list

​workflow cancel

​codemod@next jssg

jssg run

​jssg test

​codemod@next init

​codemod@next login

​codemod@next logout

​codemod@next whoami

​codemod@next publish

​codemod@next search

​codemod@next cache

​cache info

​cache list

​cache clear

​cache prune

Go to:

`codemod@next workflow`

`workflow run`

`workflow resume`

`workflow validate`

`workflow status`

`workflow list`

`workflow cancel`

`codemod@next jssg`

`jssg run`

`jssg test`

`codemod@next init`

`codemod@next login`

`codemod@next logout`

`codemod@next whoami`

`codemod@next publish`

`codemod@next search`

`codemod@next cache`

`cache info`

`cache list`

`cache clear`

`cache prune`