> ## Documentation Index > Fetch the complete documentation index at: https://docs.codemod.com/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. New to Codemod? Follow the step-by-step guide to scaffold, test, and publish your first codemod. *** ## 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](/package-structure). 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**: [Workflow Reference](/workflows/reference) **`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 [Workflow Reference: JSSG Step](/workflows/reference#jssg-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: 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 (only applies to strict mode). Comparison strictness level (default: `strict`): * `strict` - Exact string equality * `cst` - Compare Concrete Syntax Trees (includes all tokens, preserves ordering) * `ast` - Compare Abstract Syntax Trees (ignores formatting, preserves ordering) * `loose` - Loose AST comparison (ignores formatting and ordering of unordered nodes like object properties, imports) Supported languages: JavaScript, TypeScript, Python, Go, Rust, JSON. 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] ``` When you run `codemod init` in interactive mode, you'll be prompted to create a GitHub Actions workflow for publishing. This creates `.github/workflows/publish.yml` with: * **Single codemod repository**: Triggers on `v*` tags (e.g., `v1.0.0`) * **Monorepo setup**: Triggers on `*@v*` tags (e.g., `my-codemod@v1.0.0`) and extracts the codemod name from the tag Both workflows use [trusted publishers](/publishing#trusted-publishers) with OIDC for secure, passwordless publishing. [See the publishing guide](/publishing#complete-github-actions-workflow) for detailed workflow examples. 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] ``` Path to codemod directory (defaults to current directory). Package metadata (name, version, access level, etc.) is read from `codemod.yaml`. See [Package Structure](/package-structure#package-metadata-codemod-yaml) for configuration options. Learn about all publishing methods including API keys, trusted publishers (OIDC), and CI/CD setup. ### `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.