> ## Documentation Index
> Fetch the complete documentation index at: https://codemodcom.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Codemod CLI
> Scaffold, publish, and run codemod projects, recipes, or packages from your terminal using Codemod's open-source CLI.
export const APIKeyDemo = () => {
return
;
};
export const CLIDemo = () => {
return
;
};
## Quick Start
```bash theme={null}
npx codemod init
```
This scaffolds a new codemod project in the current directory.
```bash theme={null}
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.
```bash theme={null}
npx codemod publish
```
This publishes your codemod to the registry (you may need to login first).
```bash theme={null}
npx codemod @codemod/my-test-pkg
```
Run your published codemod directly from the [Codemod Registry](https://app.codemod.com/registry).
For more details on building and running Codemod packages, see the [Codemod Packages documentation](#cli-command-reference).
***
## Command Relationships
The Codemod CLI provides different commands for different stages of development:
### High-Level Commands (Production)
```bash theme={null}
# 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)
```bash theme={null}
# 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
```bash theme={null}
# 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](/cli/packages/quickstart).
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](/cli/packages/building-workflows)
**`workflow run`**
Run a complete Codemod package.
* Use `npx codemod workflow run -w ` for local Codemod packages and directories
* Use `npx codemod ` to run packages directly from the [Codemod Registry](https://app.codemod.com/registry)
```bash Running a local workflow theme={null}
npx codemod workflow run -w
```
```bash Running a workflow from Codemod Registry theme={null}
npx codemod
```
Path to workflow file or directory.
Target directory to run the workflow on.
```bash theme={null}
# 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
```
Pass key=value pairs to your workflow. Parameters are exposed to jssg transforms via `options.params`.
```bash theme={null}
# 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.
```bash theme={null}
npx codemod workflow resume -i [-t ] [--trigger-all]
```
Workflow run ID.
Task ID to trigger (can be specified multiple times).
Trigger all awaiting tasks.
**`workflow validate`**
Validate a workflow file.
```bash theme={null}
npx codemod workflow validate -w
```
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.
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.
```bash theme={null}
npx codemod workflow status -i
```
Workflow run ID.
**`workflow list`**
List workflow runs.
```bash theme={null}
npx codemod workflow list [-l ]
```
Number of workflow runs to show. (default: 10)
**`workflow cancel`**
Cancel a workflow run.
```bash theme={null}
npx codemod workflow cancel -i
```
Workflow run ID.
### `codemod jssg`
Run [jssg (JS ast-grep)](/jssg/quickstart) 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](/cli/packages/building-workflows#js-ast-grep-step).
**Learn more**: [jssg documentation](/jssg/quickstart)
Create a JS/TS file that exports your codemod logic.
```bash theme={null}
npx codemod jssg run my-codemod.js ./src --language javascript
```
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:
```bash theme={null}
npx codemod jssg test my-codemod.js --language javascript
```
**`jssg run`**
Run a JS ast-grep (jssg) codemod.
```bash theme={null}
npx codemod jssg run [options]
```
Path to the JS ast-grep (jssg) codemod file (JS/TS).
Directory to apply the codemod to.
Target language (e.g., `javascript`, `typescript`, `python`, `java`, `cpp`, `php`, `kotlin`, etc.).
Comma-separated list of file extensions to process.
Do not respect `.gitignore` files.
Include hidden files and directories in the scan.
Maximum number of concurrent threads to use.
Perform a dry-run to see the changes without applying them.
**`jssg test`**
Test a JS ast-grep(jssg) codemod using before/after fixtures.
```bash theme={null}
npx codemod jssg test [options]
```
Path to the JS ast-grep (jssg) codemod file, which is a JS/TS file.
Target language (e.g., `javascript`, `typescript`, `python`, `java`, `cpp`, `php`, `kotlin`, etc.).
The directory containing your tests (default: `"tests"`).
A pattern to run only tests whose names match the filter.
The output format for test results. Can be `console`, `json`, or `terse`.
Show detailed output, including diffs for failed tests.
The number of context lines to show in diffs (default: 3).
Ignore whitespace differences when comparing test outputs.
Test timeout in seconds (default: 30).
Maximum number of concurrent threads to use for running tests.
Run tests sequentially instead of in parallel.
Stop the test run on the first failure.
Create or update the `expected` files with the output of the codemod. (`-u` is a shorthand for `--update-snapshots`)
A comma-separated list of test patterns that are expected to fail.
Enable watch mode to automatically re-run tests when files change.
* 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).
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.
```bash theme={null}
npx codemod init [PATH] [options]
```
Project directory name.
Project name (defaults to directory name).
Project type: `ast-grep-js`.
* `shell`: Shell script-based codemods
* `ast-grep-yaml`: YAML-based ast-grep codemods
Target language.
Project description.
Author name and email.
License.
Make package private.
Overwrite existing files.
Use defaults without prompts.
### `codemod login`
Login to a registry.
```bash theme={null}
npx codemod login [--api-key ] [--registry ] [--scope ]
```
Authenticate using an API key. Skips the browser login & is ideal for CI.
Registry URL.
Organization or user scope for publishing.
Need a key? Generate one in the Codemod app [here ->](https://app.codemod.com/api-keys).
### `codemod logout`
Logout from a registry.
```bash theme={null}
npx codemod logout [--registry ] [--all]
```
Registry URL to logout from.
Logout from all registries.
### `codemod whoami`
Show current authentication status.
```bash theme={null}
npx codemod whoami [--registry ] [--detailed]
```
Registry URL to check.
Show detailed information including token scopes.
### `codemod publish`
Publish a Codemod package to a registry.
```bash theme={null}
npx codemod publish [PATH] [options]
```
Path to codemod directory.
Explicit version override.
Target registry URL.
Tag for the release.
Access level (`public`, `private`).
Validate and pack without uploading.
Publishing from CI or on behalf of an organization? Install the [Codemod GitHub App](https://github.com/apps/codemod) on the target repos.
Use this method when your organization has installed the [Codemod GitHub App](https://github.com/apps/codemod). The app injects `CODEMOD_TOKEN` automatically—no separate login step needed.
```yaml theme={null}
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
```
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:**
```yaml theme={null}
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 }}
```
```bash theme={null}
# 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.
```bash theme={null}
npx codemod unpublish [options]
```
Package name (e.g., `@org/my-codemod` or `my-codemod`).
Specific semver to unpublish. Requires confirmation.
Unpublish **all** versions (irreversible). Confirmation required.
Target registry URL.
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.
```bash theme={null}
# 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.
```bash theme={null}
npx codemod search [OPTIONS] [QUERY]
```
Search query
Filter by programming language
Filter by framework
Filter by category
Number of results to return (default: 20)
Pagination offset (default: 0)
Filter by organization scope
Registry URL
Output format (default: table). Possible values: table, json, yaml
Search for codemods related to React:
```bash theme={null}
npx codemod search react
```
Filter by language and category:
```bash theme={null}
npx codemod search --language typescript --category migration
```
Get results in JSON format:
```bash theme={null}
npx codemod search --format json next
```
### `codemod cache`
Manage the local package cache for Codemod packages.
**`cache info`**
Show cache information and statistics.
```bash theme={null}
npx codemod cache info
```
**`cache list`**
List cached packages.
```bash theme={null}
npx codemod cache list [--detailed]
```
Show package details.
**`cache clear`**
Clear cache for a specific package, or all packages.
```bash theme={null}
npx codemod cache clear [PACKAGE] [--all]
```
Package name (e.g., `@org/package` or `package`).
Clear all cached packages.
**`cache prune`**
Prune old or unused cache entries.
```bash theme={null}
npx codemod cache prune [--max-age ] [--dry-run]
```
Maximum age in days to keep (default: 30).
Dry run - show what would be removed.