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

> [card] [Quickstart](https://docs.codemod.com/community/oss-quickstart.md)
>
> 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
```

> [!NOTE]
>
> **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.

***

## Telemetry

When analytics are enabled, the CLI sends product telemetry to PostHog (and a separate Scarf
gateway for install/usage signals). Logged-in users are keyed by their Codemod account id.
Anonymous installs use a local telemetry id and are never aliased to an account.

For logged-in sessions only, the CLI may also send a separate PostHog `$set` with the account
**email** so dashboards can show people instead of raw UUIDs. That update is PostHog-only (not
Scarf), deduped locally, and skipped when you opt out.

Disable all of this for a single invocation with `--disable-analytics`, or by setting
`DISABLE_ANALYTICS=true` / `DISABLE_ANALYTICS=1` in the environment. The flag works on explicit
commands and on implicit package runs such as `npx codemod @org/package --disable-analytics`.

More detail: [Telemetry compliance](https://codemod.com/telemetry-compliance).

***

# CLI Command Reference

Codemod CLI is accessible using the `npx codemod` command. The following commands and options are available:

### `codemod ai`

> [!NOTE]
>
> In an interactive terminal, bare `npx codemod` opens a launcher. In npm-based usage, that launcher refreshes to the latest published CLI before prompting you to create a package or run one from the registry. In non-interactive contexts, the CLI prints next steps and exits with status `1`.

Manage Master Codemod Skill (MCS) lifecycle for supported harnesses.

**`ai`**

Install the `codemod` MCS skill package, configure Codemod MCP, and install the universal `/codemod` entrypoint where the harness supports it.

```bash theme={null}
npx codemod ai [--harness <claude|goose|opencode|cursor|codex|auto>] [--project|--user] [--force] [--no-interactive] [--update-policy <manual|notify|auto-safe>] [--update-source <local|registry|URL>] [--require-signed-manifest|--allow-unsigned-manifest] [--format <logs|table|json|yaml>]
```

Interactive prompts are enabled by default in TTY sessions. Use `--no-interactive` to skip prompts and use flags/defaults directly.

With `--harness auto` (the default), install first checks whether it is running inside a coding agent (Claude Code, Codex, Cursor, OpenCode, Goose or Antigravity) and sets up that agent. Otherwise it looks for an agent folder or config file in the project, such as `.claude`, `.cursor`, `.codex` or `opencode.json`, and prefers Claude Code when it finds several. If it finds neither, it sets up Claude Code and warns, so pass `--harness` to choose another agent. The output says which agent was set up and why, marks files that a re-run left unchanged as up to date, and ends with numbered next steps for that agent, such as approving the MCP server in Claude Code or trusting the folder in Codex.

Along with skill files, install writes or updates a Codemod MCP server entry. Project installs (`--project`) write a portable launcher pinned to the CLI version that ran the install, so the config can be committed and used on other machines and checkouts:

```json theme={null}
{
  "mcpServers": {
    "codemod": {
      "command": "npx",
      "args": ["-y", "codemod@<installing CLI version>", "mcp"]
    }
  }
}
```

User installs (`--user`) stay on the current machine, so they launch the installed `codemod` executable directly. If the CLI itself was run through `npx`, its cached executable is temporary, so user installs fall back to `codemod` on `PATH` (outside the npx cache) or the same pinned `npx` launcher. Re-running `ai --project` repairs one known broken entry without `--force`: a project entry whose command is an absolute path to an executable inside npm's npx cache (`_npx`), which earlier releases wrote. Every other existing `codemod` entry is kept and reported as a conflict, including absolute paths outside the npx cache, older pinned `codemod@<version>` launchers, and all user-scope entries. Re-run with `--force` to replace it.

Prerequisites for project installs:

* The project MCP launcher needs Node.js and npm (`npx`) on every machine that uses the committed config. The first launch of a pinned version downloads it from the npm registry unless it is already in the npm cache.
* If npm is not available, use `--user` with an installed `codemod` executable instead.
* The Claude periodic update hook runs a POSIX shell script. Claude Code runs hook commands with `sh` on macOS and Linux and with Git Bash on Windows, so Windows machines need Git for Windows; the hook does not run under PowerShell.

For Opencode, install writes `opencode.json` using the Opencode-specific `mcp` schema instead of `mcpServers`.

MCP config paths by harness and scope:

* `claude`: `./.mcp.json` (project), `~/.claude.json` (user, the same file `claude mcp add -s user` writes; other keys in it are kept)
* `goose`: `./.goose/mcp.json` (project), `~/.config/goose/mcp.json` (user)
* `opencode`: `./opencode.json` (project), `~/.config/opencode/opencode.json` (user)
* `cursor`: `./.cursor/mcp.json` (project), `~/.cursor/mcp.json` (user)
* `codex` (CLI + macOS app): `./.codex/config.toml` (project), `~/.codex/config.toml` (user) under `[mcp_servers.codemod]`

If a conflicting Codemod MCP entry already exists, re-run with `--force` to overwrite it. For Opencode, Codemod leaves any legacy `./.opencode/mcp.json` or `~/.opencode/mcp.json` file in place to avoid deleting unrelated MCP servers.

`ai` also upserts a managed Codemod discovery section in harness discovery guides (project root for `--project`, home directory for `--user`) without duplicating entries:

* `claude`: `CLAUDE.md`
* `goose`: `AGENTS.md` and `.goosehints`
* `cursor`: `AGENTS.md`
* `opencode`: `AGENTS.md`
* `codex`: `AGENTS.md`
  `ai` also installs `/codemod` where the harness has a native command or workflow file surface:
* `claude`: `./.claude/commands/codemod.md` (project), `~/.claude/commands/codemod.md` (user)
* `goose`: `~/.config/goose/recipes/codemod.yaml` + `~/.config/goose/config.yaml` registration (user only)
* `opencode`: `./.opencode/commands/codemod.md` (project), `~/.config/opencode/commands/codemod.md` (user)
* `cursor`: `./.cursor/commands/codemod.md` (project), `~/.cursor/commands/codemod.md` (user)
  The installed `/codemod` command routes by intent:
* create, scaffold, or refine codemods -> codemod authoring flow
* search, run, or apply existing codemods -> registry discovery and execution flow

The generated Codemod skill package includes these authored files:

* `SKILL.md`: the main skill instructions and Codemod-specific authoring and execution defaults
* `agents/openai.yaml`: the Codemod agent interface definition used by compatible harnesses
* `commands/codemod.md`: the `/codemod` command routing rules for harnesses with a native command surface

The installed skill also points users to CLI fallbacks when MCP is unavailable or blocked. The main user-reproducible commands are:

* `npx codemod ai docs`: list docs resources exposed through the CLI
* `npx codemod ai docs <resource-id>`: read a specific docs resource such as `codemod-cli`, `codemod-creation-workflow`, or `codemod-troubleshooting`
* `npx codemod ai dump-ast <file>` or `npx codemod ai dump-ast --`: inspect AST shape for a file or stdin
* `npx codemod ai node-types <language>`: inspect tree-sitter node kinds for a language
* `npx codemod ai call validate_codemod_package --input '{"package_path":"."}'`: validate whether a codemod package still contains starter scaffold markers or other package-surface issues
* `npx codemod ai feedback --category <category> --message <message>`: submit short anonymous platform feedback after consent is recorded

`ai` also wires a periodic, cooldown-protected update check trigger:

* `claude`: `hooks.SessionStart` command in `./.claude/settings.json` (project) or `~/.claude/settings.json` (user). The project hook runs `"$CLAUDE_PROJECT_DIR"/.claude/codemod/periodic-update/check-updates.sh`, so it keeps working after the project is cloned or moved. Re-running `ai` replaces a project hook that an earlier install wrote with an absolute runner path, including one written from a different checkout.
  Only unmodified generated hooks with an unambiguous absolute runner command are migrated automatically. Commands containing whitespace (including old unquoted paths with spaces), quoting, arguments or shell syntax are preserved, as are hooks with custom matchers, timeouts or other fields. Review and remove obsolete preserved hooks manually when moving a checkout; install adds the portable hook without deleting those commands.
* `cursor`: `hooks.afterAgentResponse` command in `./.cursor/hooks.json` (project) or `~/.cursor/hooks.json` (user)
* `opencode`: plugin `codemod-periodic-update.js` in `./.opencode/plugins/` (project) or `~/.config/opencode/plugins/` (user), listening to `session.idle`
* `goose`: managed `codemod-periodic-update` block in `./.goosehints` (project) or `~/.config/goose/.goosehints` (user) as fallback guidance
* `codex`: `notify = ["sh", "<runner>"]` in `./.codex/config.toml` (project) or `~/.codex/config.toml` (user)
  Managed update policy is install-flag driven and shared by install-time reconciliation and periodic checks:
* `--update-policy <manual|notify|auto-safe>` (default: `auto-safe`)
* `--update-source <local|registry|URL>` (default: `registry`)
* `--require-signed-manifest` or `--allow-unsigned-manifest` (optional override)
  `--update-source` only accepts `local`, `registry`, or an absolute `http(s)` URL (legacy `registry:`/`url:` aliases are rejected).
  Project periodic runners use the same pinned `npx -y codemod@<installing CLI version>` launcher as project MCP, even when another global CLI version is installed. User runners retain their local executable/PATH fallback. Periodic runs enforce signed manifest verification via `--require-signed-manifest` in the generated runner command.
  After install, restart or reload your harness session so newly installed skills and command entrypoints are picked up.

**`ai feedback`**

Submit short anonymous platform feedback for Codemod AI, MCP, JSSG, workflows, docs, CLI, registry, or related surfaces. The command records anonymous feedback consent in the user-wide Codemod config, including the timestamp at which this OS user allowed feedback submission.

```bash theme={null}
npx codemod ai feedback --category <category> --message <message>
```

Recommended categories are `jssg`, `workflow`, `ai-docs`, `mcp`, `cli`, `registry`, `package-validation`, and `other`.

Examples:

```bash theme={null}
npx codemod ai feedback --category jssg --message "I wish JSSG had clearer examples for multi-file transforms."
npx codemod ai feedback --category ai-docs --message "The docs resource for runtime capabilities should explain which Node APIs are unavailable."
```

Feedback is anonymous. Do not include source code, secrets, auth tokens, private repository paths, user identity, or long transcripts in the message.

**`ai update`**

Run managed update reconciliation/apply through CLI (same policy engine used by periodic hooks).

```bash theme={null}
npx codemod ai update [--harness <claude|goose|opencode|cursor|codex|auto>] [--project|--user] [--force] [--no-interactive] [--update-policy <manual|notify|auto-safe>] [--update-source <local|registry|URL>] [--require-signed-manifest|--allow-unsigned-manifest] [--format <logs|table|json|yaml>]
```

If managed install state is missing, `ai update` automatically falls back to an install flow and then applies update reconciliation.

`ai` performs internal skill validation checks during install flow.

**`ai list`**

List installed Codemod skills for a harness.

```bash theme={null}
npx codemod ai list [--harness <claude|goose|opencode|cursor|codex|auto>] [--format <logs|table|json|yaml>]
```

Use this command to inspect which Codemod-managed skills are already installed for a given harness before running `codemod ai` again or troubleshooting harness setup.

**`ai dump-ast`**

Dump AST nodes for a source file or stdin using the same parser surface exposed through Codemod MCP.

```bash theme={null}
npx codemod ai dump-ast [FILE] [--language <language>] [--json]
```

* Omit `FILE` or pass `-` to read from stdin.
* If you do not pass `--language`, the CLI infers it from the file extension when possible and otherwise defaults to `tsx` for stdin.

```bash theme={null}
# Parse a file and print AST text
npx codemod ai dump-ast ./src/component.tsx

# Parse stdin as TypeScript and emit JSON
cat ./src/index.ts | npx codemod ai dump-ast - --language typescript --json
```

**`ai node-types`**

Print tree-sitter node types for a supported language.

```bash theme={null}
npx codemod ai node-types <language> [--json]
```

```bash theme={null}
npx codemod ai node-types tsx
npx codemod ai node-types python --json
```

**`ai docs`**

List, read, or search Codemod AI documentation resources from the CLI.

```bash theme={null}
npx codemod ai docs [query...] [--json]
```

* Run without a query to list available docs-backed resources.
* Pass a resource name or URI to read it.
* Pass a search phrase to search across available resources.

```bash theme={null}
# List available docs resources
npx codemod ai docs

# Read one resource by name
npx codemod ai docs codemod-cli-instructions

# Search across docs-backed resources
npx codemod ai docs semantic analysis
```

**`ai tools` and `ai tool`**

Inspect MCP-equivalent tools exposed by the CLI.

```bash theme={null}
npx codemod ai tools [--json]
npx codemod ai tool <name> [--json]
```

* `ai tools` lists available tool names and descriptions.
* `ai tool <name>` prints metadata and the JSON input schema for a single tool.

**`ai call`**

Call an MCP-equivalent tool directly from the CLI with JSON input.

```bash theme={null}
npx codemod ai call <name> [--input <JSON|@path|- >]
```

* Omit `--input` to pass an empty object (`{}`).
* Use `--input @request.json` to load input from a file.
* Use `--input -` to read JSON input from stdin.

```bash theme={null}
npx codemod ai call dump_ast --input '{"language":"tsx","source":"const x = 1;"}'
```

**`ai resources` and `ai resource`**

Inspect and read MCP-equivalent resources exposed by the CLI.

```bash theme={null}
npx codemod ai resources [--json]
npx codemod ai resource <uri-or-name> [--json]
```

* `ai resources` lists the available resource names and URIs.
* `ai resource` reads one resource by URI or resource name.

### Package skill install (prompted from package run)

Install a package skill from registry metadata into harness skill paths.
The installer copies the authored skill directory recursively from the package (`agents/skill/<skill-name>/`), including any additional files you add (for example extra `.md` references).
This flow also updates managed Codemod discovery hints in harness discovery guides (`CLAUDE.md` for Claude, `AGENTS.md` and `.goosehints` for Goose, `AGENTS.md` for Cursor/OpenCode/Codex) without duplication, then prompts you to restart/reload the harness session.

```bash theme={null}
npx codemod <package-id>
```

In interactive TTY sessions, `npx codemod <package-id>` prompts for harness/scope/overwrite when installable skill behavior is available.

> [!NOTE]
>
> Behavior-aware package runtime:
>
> * **Workflow-only package**: `npx codemod <package-id>` runs the workflow behavior.
> * **Skill-only package**: `npx codemod <package-id>` does not run a no-op workflow. It returns install guidance and, in interactive terminals, can prompt to install the skill.
> * **Workflow + skill package**: `npx codemod <package-id>` runs workflow behavior and can optionally prompt to install skill behavior after run completion.
> * **Multi-workflow package**: when the package's `codemod.yaml` declares multiple workflows under `workflows:`, the default workflow runs unless you pass `--workflow <name>`. In an interactive terminal with no flag, the CLI shows a picker.

**AI-native error codes**

| Code | Exit | Meaning |
| - | - | - |
| `E_SKILL_PACKAGE_NOT_FOUND` | `27` | Unknown package id / unresolved package version |
| `E_SKILL_PACKAGE_INSTALL_FAILED` | `28` | Registry resolution, metadata parse, or install write failure |

Example machine-readable failure (`--format json`):

```json theme={null}
{
  "ok": false,
  "code": "E_SKILL_PACKAGE_NOT_FOUND",
  "exit_code": 27,
  "message": "Unknown skill package id: jest-to-vitestx",
  "hint": "Run `codemod search <migration> --format json` to locate a valid package id."
}
```

### `codemod workflow`

Manage and execute [Codemod packages](https://docs.codemod.com/community/package-structure.md).

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](https://docs.codemod.com/community/workflows/reference.md)

**`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](https://app.codemod.com/registry)

```bash Running a local workflow theme={null}
npx codemod workflow run -w <workflow.yaml|directory>
```

```bash Running a workflow from Codemod Registry theme={null}
npx codemod <package-name>
```

**-w, --workflow \<PATH>** `string` *required*

Path to workflow file or directory.

**-t, --target \<PATH>** `string`

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

**--param \<KEY=VALUE>** `string`

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

**--install-skill** `boolean`

In non-interactive runs, execute `install-skill` workflow steps instead of skipping them by default.

```bash theme={null}
npx codemod workflow run -w workflow.yaml --no-interactive --install-skill
npx codemod <package-name> --no-interactive --install-skill
```

**--workflow-name \<NAME>** `string`

When the package directory's `codemod.yaml` declares multiple workflows under `workflows:`, pick which variant to run.

Without this flag, the entry marked `default: true` runs (or the first entry if none is flagged). When stdin/stdout are interactive and no flag is given, the CLI shows a picker.

```bash theme={null}
# Run a named workflow defined in the package's codemod.yaml
npx codemod workflow run -w ./my-codemod --workflow-name sharded
```

Errors out if the name doesn't match any declared workflow, or if the source path is a workflow file (rather than a package directory) — in that case the file IS the workflow.

**--llm-usage-output \<PATH>** `string`

Write provider-reported nested LLM usage for the current package run to a JSON file.

This output is only populated for LLM requests made by nested codemods during `npx codemod <package-name>` or other package-run flows. The file contains aggregated request counts by provider, model, outcome, and token-usage bucket, and it does not include prompts, API keys, or other request payload data.

```bash theme={null}
# Capture nested LLM usage while running a registry package
npx codemod @org/my-package --llm-usage-output ./artifacts/llm-usage.json

# Capture nested LLM usage for a local package run
npx codemod workflow run -w ./my-codemod --llm-usage-output ./artifacts/llm-usage.json
```

The CLI creates parent directories as needed and overwrites the file with the current run's data.

**`workflow resume`**

Resume a paused workflow.

```bash theme={null}
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.

**--install-skill** `boolean`

In non-interactive resume runs, execute pending `install-skill` workflow steps instead of skipping them by default.

```bash theme={null}
npx codemod workflow resume -w workflow.yaml -i <ID> --trigger-all --no-interactive --install-skill
```

**`workflow validate`**

Validate a workflow file.

```bash theme={null}
npx codemod workflow validate -w <workflow.yaml>
```

`workflow validate` is capability-aware for codemod packages:

* **Workflow-only** package: validates workflow behavior.
* **Skill-only** package: validates workflow `install-skill` behavior plus authored skill layout (`agents/skill/<skill-name>/...`).
* **Workflow + skill** package: validates both executable workflow and authored skill behavior.

**-w, --workflow \<FILE>** `string` *required*

Path to workflow file or codemod package directory.

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

> [!NOTE]
>
> Why validate?
>
> Validation catches issues before execution, saving time and preventing runtime errors.

> [accordion] Validation vs. Logical Correctness
>
> For workflow behavior, `workflow validate` 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 <ID>
```

**-i, --id \<ID>** `string` *required*

Workflow run ID.

**`workflow list`**

List workflow runs.

```bash theme={null}
npx codemod workflow list [-l <LIMIT>]
```

**-l, --limit \<LIMIT>** `number`

Number of workflow runs to show. (default: 10)

**`workflow cancel`**

Cancel a workflow run.

```bash theme={null}
npx codemod workflow cancel -i <ID>
```

**-i, --id \<ID>** `string` *required*

Workflow run ID.

### `codemod jssg`

Run [jssg (JS ast-grep)](https://docs.codemod.com/community/jssg) 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

> [!TIP]
>
> For production, embed your jssg transform in a workflow using a `js-ast-grep` step. See [Workflow Reference: JSSG Step](https://docs.codemod.com/community/workflows/reference.md#jssg-step).

**Learn more**: [jssg documentation](https://docs.codemod.com/community/jssg)

**1. Write your codemod**

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

**2. Run your codemod**

```bash theme={null}
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**

Use the `input/` + `expected/` layout when the codemod creates or deletes files. The runner compares the whole directory snapshot but still reports results per file.

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 <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`, `json`, `yaml`, `xml`, `toml`, 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. Supports both single-file `input.*`/`expected.*` cases and directory snapshot fixtures using `input/` + `expected/`.

```bash theme={null}
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`, `json`, `yaml`, `xml`, `toml`, etc.).

**--test-directory** `string`

The parent directory containing your test case subdirectories (default: `"tests"`). Do not pass a specific test case subdirectory — use `--filter` instead.

**--filter** `string`

A pattern to run only tests whose names match the filter. Single-file fixtures use the test case directory name. Directory snapshot fixtures are still reported per file, using names like `<fixture>_<relative-path>`.

**--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 (only applies to strict mode).

**--strictness \<LEVEL>** `string`

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.

**--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. For directory snapshot fixtures, this also creates missing expected files and removes stale ones. (`-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.

> [accordion] 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).

> [accordion] 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.

```bash theme={null}
npx codemod init [PATH] [options]
```

In interactive mode, `codemod init` prompts you to choose between a `jssg codemod`, `multi-step workflow`, or `agent skill codemod`. If you select a workflow, you can optionally scaffold an agent skill.

You'll also be prompted to create a GitHub Actions publishing workflow. This generates `.github/workflows/publish.yml`:

* **Single codemod repo**: Triggers on `v*` tags (e.g., `v1.0.0`)
* **Monorepo**: Triggers on `*@v*` tags (e.g., `my-codemod@v1.0.0`) and extracts the codemod name

Both workflows use [trusted publishers](https://docs.codemod.com/community/publishing.md#trusted-publishers) with OIDC for secure, passwordless publishing.

[See the publishing guide](https://docs.codemod.com/community/publishing.md#complete-github-actions-workflow) for detailed workflow examples.

**\[PATH]** `string`

Project directory name.

**--name \<NAME>** `string`

Project name (defaults to directory name).

Required in `--no-interactive` mode when the project name cannot be derived from `[PATH]` (for example, when `[PATH]` is `.`, `..`, or another path without a final directory component).

**--project-type \<PROJECT\_TYPE>** `string`

Workflow project type: `ast-grep-js` or `hybrid`.
Mutually exclusive with `--skill`.

Required in `--no-interactive` mode for workflow packages.

> [accordion] More package types (advanced)
>
> * `shell`: Shell script-based codemods
> * `ast-grep-yaml`: YAML-based ast-grep codemods

**--skill** `boolean`

Scaffold a skill-only package with a workflow-first template (`workflow.yaml` contains `install-skill`) and authored files under `agents/skill/<skill-name>/`.

The generated `SKILL.md` uses the authored package skill markers:

* `codemod-compatibility: skill-package-v1`
* `codemod-skill-version: 0.1.0`

Mutually exclusive with `--with-skill` and `--project-type`.

**--with-skill** `boolean`

Scaffold a workflow + skill package. This keeps executable workflow files, appends an `install-skill` node, and creates authored skill files under `agents/skill/<skill-name>/`.

The generated authored skill uses `skill-package-v1`, not the built-in `mcs-v1` core skill marker.

Mutually exclusive with `--skill`.

**--package-manager \<PACKAGE\_MANAGER>** `string`

Package manager.

Required in `--no-interactive` mode for `ast-grep-js`, `hybrid`, and `--workspace`.

**--language \<LANGUAGE>** `string`

Target language.

Required in `--no-interactive` mode.

**--description \<DESCRIPTION>** `string`

Project description.

Required in `--no-interactive` mode.

**--author \<AUTHOR>** `string`

Author name and email.

Required in `--no-interactive` mode.

**--license \<LICENSE>** `string`

License.

Required in `--no-interactive` mode.

**--git-repository-url \<URL>** `string`

Git repository URL stored as `repository` in `codemod.yaml`.

**--private** `boolean`

Make package private.

**--force** `boolean`

Overwrite existing files.

**--no-interactive** `boolean`

Use defaults without prompts.
In this mode, pass the values that would normally come from prompts.

### `codemod login`

Login to a registry.

```bash theme={null}
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.

> [!TIP]
>
> 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 <REGISTRY>] [--all]
```

**--registry \<REGISTRY>** `string`

Registry URL to logout from.

**--all** `boolean`

Logout from all registries.

### `codemod whoami`

Show current authentication status.

```bash theme={null}
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.

```bash theme={null}
npx codemod publish [PATH]
```

**\[PATH]** `string`

Path to codemod directory (defaults to current directory).

> [!NOTE]
>
> Package metadata (name, version, access level, etc.) is read from `codemod.yaml`. See [Package Structure](https://docs.codemod.com/community/package-structure.md#package-metadata-codemod-yaml) for configuration options.

> [card] [Publishing Guide](https://docs.codemod.com/community/publishing.md)
>
> 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 <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.

> [!TIP]
>
> The CLI always prompts for confirmation when `--version` or `--force` is used. This interactive step cannot be bypassed programmatically.

> [accordion] Examples
>
> ```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]
```

**\[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

> [accordion] Examples
>
> 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]
```

**--detailed** `boolean`

Show package details.

**`cache clear`**

Clear cache for a specific package, or all packages.

```bash theme={null}
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.

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.