> ## 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 title="Quickstart" icon="rocket" href="/oss-quickstart">
  New to Codemod? Follow the step-by-step guide to scaffold, test, and publish your first codemod.
</Card>

***

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

<Info>
  **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.
</Info>

***

# CLI Command Reference

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

### `codemod ai`

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

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.

Along with skill files, install writes or updates a Codemod MCP server entry:

```json theme={null}
{
  "mcpServers": {
    "codemod": {
      "command": "npx",
      "args": ["codemod@latest", "mcp"]
    }
  }
}
```

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), `~/.mcp.json` (user)
* `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
  `ai` also wires a periodic, cooldown-protected update check trigger:
* `claude`: `hooks.SessionStart` command in `./.claude/settings.json` (project) or `~/.claude/settings.json` (user)
* `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).
  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 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.

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

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

**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](/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 <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)

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

<ResponseField name="-w, --workflow <PATH>" type="string" required>
  Path to workflow file or directory.
</ResponseField>

<ResponseField name="-t, --target <PATH>" type="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
  ```
</ResponseField>

<ResponseField name="--param <KEY=VALUE>" type="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
  ```
</ResponseField>

<ResponseField name="--install-skill" type="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
  ```
</ResponseField>

<ResponseField name="--workflow-name <NAME>" type="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.
</ResponseField>

**`workflow resume`**

Resume a paused workflow.

```bash theme={null}
npx codemod workflow resume -i <ID> [-t <TASK>] [--trigger-all]
```

<ResponseField name="-i, --id <ID>" type="string" required>
  Workflow run ID.
</ResponseField>

<ResponseField name="-t, --task <TASK>" type="string">
  Task ID to trigger (can be specified multiple times).
</ResponseField>

<ResponseField name="--trigger-all" type="boolean">
  Trigger all awaiting tasks.
</ResponseField>

<ResponseField name="--install-skill" type="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
  ```
</ResponseField>

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

<ResponseField name="-w, --workflow <FILE>" type="string" required>
  Path to workflow file or codemod package directory.
</ResponseField>

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

<Info>
  Why validate?

  Validation catches issues before execution, saving time and preventing runtime errors.
</Info>

<Accordion title="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
</Accordion>

**`workflow status`**

Show workflow run status.

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

<ResponseField name="-i, --id <ID>" type="string" required>
  Workflow run ID.
</ResponseField>

**`workflow list`**

List workflow runs.

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

<ResponseField name="-l, --limit <LIMIT>" type="number">
  Number of workflow runs to show. (default: 10)
</ResponseField>

**`workflow cancel`**

Cancel a workflow run.

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

<ResponseField name="-i, --id <ID>" type="string" required>
  Workflow run ID.
</ResponseField>

### `codemod jssg`

Run [jssg (JS ast-grep)](/jssg/intro) 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](/workflows/reference#jssg-step).
</Tip>

**Learn more**: [jssg documentation](/jssg/intro)

<Steps>
  <Step title="Write your codemod">
    Create a JS/TS file that exports your codemod logic.
  </Step>

  <Step title="Run your codemod">
    ```bash theme={null}
    npx codemod jssg run my-codemod.js ./src --language javascript
    ```
  </Step>

  <Step title="Test your codemod">
    Organize your tests as follows:

    <Tree>
      <Tree.Folder name="tests" defaultOpen>
        <Tree.Folder name="simple-transform" defaultOpen>
          <Tree.File name="input.js" />

          <Tree.File name="expected.js" />
        </Tree.Folder>

        <Tree.Folder name="multi-file-case" defaultOpen>
          <Tree.Folder name="input" defaultOpen>
            <Tree.File name="file1.js" />

            <Tree.File name="file2.js" />
          </Tree.Folder>

          <Tree.Folder name="expected" defaultOpen>
            <Tree.File name="file1.js" />

            <Tree.File name="file2.js" />
          </Tree.Folder>
        </Tree.Folder>
      </Tree.Folder>
    </Tree>

    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
    ```
  </Step>
</Steps>

**`jssg run`**

Run a JS ast-grep (jssg) codemod.

```bash theme={null}
npx codemod jssg run <codemod_file> <target_directory> [options]
```

<ResponseField name="codemod_file" type="string" required>
  Path to the JS ast-grep (jssg) codemod file (JS/TS).
</ResponseField>

<ResponseField name="target_directory" type="string" required>
  Directory to apply the codemod to.
</ResponseField>

<ResponseField name="--language <LANG>" type="string" required>
  Target language (e.g., `javascript`, `typescript`, `python`, `java`, `cpp`, `php`, `kotlin`, etc.).
</ResponseField>

<ResponseField name="--extensions <ext1,ext2>" type="string">
  Comma-separated list of file extensions to process.
</ResponseField>

<ResponseField name="--no-gitignore" type="boolean">
  Do not respect `.gitignore` files.
</ResponseField>

<ResponseField name="--include-hidden" type="boolean">
  Include hidden files and directories in the scan.
</ResponseField>

<ResponseField name="--max-threads <N>" type="number">
  Maximum number of concurrent threads to use.
</ResponseField>

<ResponseField name="--dry-run" type="boolean">
  Perform a dry-run to see the changes without applying them.
</ResponseField>

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

<ResponseField name="codemod_file" type="string" required>
  Path to the JS ast-grep (jssg) codemod file, which is a JS/TS file.
</ResponseField>

<ResponseField name="--language" type="string" required>
  Target language (e.g., `javascript`, `typescript`, `python`, `java`, `cpp`, `php`, `kotlin`, etc.).
</ResponseField>

<ResponseField name="--test-directory" type="string">
  The parent directory containing your test case subdirectories (default: `"tests"`). Do not pass a specific test case subdirectory — use `--filter` instead.
</ResponseField>

<ResponseField name="--filter" type="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>`.
</ResponseField>

<ResponseField name="--reporter" type="string">
  The output format for test results. Can be `console`, `json`, or `terse`.
</ResponseField>

<ResponseField name="--verbose" type="boolean">
  Show detailed output, including diffs for failed tests.
</ResponseField>

<ResponseField name="--context-lines" type="number">
  The number of context lines to show in diffs (default: 3).
</ResponseField>

<ResponseField name="--ignore-whitespace" type="boolean">
  Ignore whitespace differences when comparing test outputs (only applies to strict mode).
</ResponseField>

<ResponseField name="--strictness <LEVEL>" type="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.
</ResponseField>

<ResponseField name="--timeout" type="number">
  Test timeout in seconds (default: 30).
</ResponseField>

<ResponseField name="--max-threads" type="number">
  Maximum number of concurrent threads to use for running tests.
</ResponseField>

<ResponseField name="--sequential" type="boolean">
  Run tests sequentially instead of in parallel.
</ResponseField>

<ResponseField name="--fail-fast" type="boolean">
  Stop the test run on the first failure.
</ResponseField>

<ResponseField name="--update-snapshots, -u" type="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`)
</ResponseField>

<ResponseField name="--expect-errors" type="string">
  A comma-separated list of test patterns that are expected to fail.
</ResponseField>

<ResponseField name="--watch" type="boolean">
  Enable watch mode to automatically re-run tests when files change.
</ResponseField>

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

### `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](/publishing#trusted-publishers) with OIDC for secure, passwordless publishing.

[See the publishing guide](/publishing#complete-github-actions-workflow) for detailed workflow examples.

<ResponseField name="[PATH]" type="string">
  Project directory name.
</ResponseField>

<ResponseField name="--name <NAME>" type="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).
</ResponseField>

<ResponseField name="--project-type <PROJECT_TYPE>" type="string">
  Workflow project type: `ast-grep-js` or `hybrid`.
  Mutually exclusive with `--skill`.

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

  <Accordion title="More package types (advanced)">
    * `shell`: Shell script-based codemods
    * `ast-grep-yaml`: YAML-based ast-grep codemods
  </Accordion>
</ResponseField>

<ResponseField name="--skill" type="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`.
</ResponseField>

<ResponseField name="--with-skill" type="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`.
</ResponseField>

<ResponseField name="--package-manager <PACKAGE_MANAGER>" type="string">
  Package manager.

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

<ResponseField name="--language <LANGUAGE>" type="string">
  Target language.

  Required in `--no-interactive` mode.
</ResponseField>

<ResponseField name="--description <DESCRIPTION>" type="string">
  Project description.

  Required in `--no-interactive` mode.
</ResponseField>

<ResponseField name="--author <AUTHOR>" type="string">
  Author name and email.

  Required in `--no-interactive` mode.
</ResponseField>

<ResponseField name="--license <LICENSE>" type="string">
  License.

  Required in `--no-interactive` mode.
</ResponseField>

<ResponseField name="--git-repository-url <URL>" type="string">
  Git repository URL stored as `repository` in `codemod.yaml`.
</ResponseField>

<ResponseField name="--private" type="boolean">
  Make package private.
</ResponseField>

<ResponseField name="--force" type="boolean">
  Overwrite existing files.
</ResponseField>

<ResponseField name="--no-interactive" type="boolean">
  Use defaults without prompts.
  In this mode, pass the values that would normally come from prompts.
</ResponseField>

### `codemod login`

Login to a registry.

```bash theme={null}
npx codemod login [--api-key <API_KEY>] [--registry <REGISTRY>] [--scope <SCOPE>]
```

<ResponseField name="--api-key <API_KEY>" type="string">
  Authenticate using an API key. Skips the browser login & is ideal for CI.
</ResponseField>

<ResponseField name="--registry <REGISTRY>" type="string">
  Registry URL.
</ResponseField>

<ResponseField name="--scope <SCOPE>" type="string">
  Organization or user scope for publishing.
</ResponseField>

<Tip>
  Need a key? Generate one in the Codemod app [here ->](https://app.codemod.com/api-keys).
</Tip>

### `codemod logout`

Logout from a registry.

```bash theme={null}
npx codemod logout [--registry <REGISTRY>] [--all]
```

<ResponseField name="--registry <REGISTRY>" type="string">
  Registry URL to logout from.
</ResponseField>

<ResponseField name="--all" type="boolean">
  Logout from all registries.
</ResponseField>

### `codemod whoami`

Show current authentication status.

```bash theme={null}
npx codemod whoami [--registry <REGISTRY>] [--detailed]
```

<ResponseField name="--registry <REGISTRY>" type="string">
  Registry URL to check.
</ResponseField>

<ResponseField name="--detailed" type="boolean">
  Show detailed information including token scopes.
</ResponseField>

### `codemod publish`

Publish a Codemod package to a registry.

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

<ResponseField name="[PATH]" type="string">
  Path to codemod directory (defaults to current directory).
</ResponseField>

<Info>
  Package metadata (name, version, access level, etc.) is read from `codemod.yaml`. See [Package Structure](/package-structure#package-metadata-codemod-yaml) for configuration options.
</Info>

<Card title="Publishing Guide" icon="upload" href="/publishing">
  Learn about all publishing methods including API keys, trusted publishers (OIDC), and CI/CD setup.
</Card>

### `codemod unpublish`

Remove a package or selected version from the registry.

```bash theme={null}
npx codemod unpublish <PACKAGE> [options]
```

<ResponseField name="<PACKAGE>" type="string" required>
  Package name (e.g., `@org/my-codemod` or `my-codemod`).
</ResponseField>

<ResponseField name="--version <VERSION>" type="string">
  Specific semver to unpublish. Requires confirmation.
</ResponseField>

<ResponseField name="--force" type="boolean">
  Unpublish **all** versions (irreversible). Confirmation required.
</ResponseField>

<ResponseField name="--registry <REGISTRY>" type="string">
  Target registry URL.
</ResponseField>

<ResponseField name="--dry-run" type="boolean">
  Show what would be removed without actually unpublishing.
</ResponseField>

<Tip>
  The CLI always prompts for confirmation when `--version` or `--force` is used. This interactive step cannot be bypassed programmatically.
</Tip>

<Accordion title="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
  ```
</Accordion>

### `codemod search`

Search for packages in the registry.

```bash theme={null}
npx codemod search [OPTIONS] [QUERY]
```

<ResponseField name="[QUERY]" type="string">
  Search query
</ResponseField>

<ResponseField name="--language <LANGUAGE>" type="string">
  Filter by programming language
</ResponseField>

<ResponseField name="--framework <FRAMEWORK>" type="string">
  Filter by framework
</ResponseField>

<ResponseField name="--category <CATEGORY>" type="string">
  Filter by category
</ResponseField>

<ResponseField name="--size <SIZE>" type="number">
  Number of results to return (default: 20)
</ResponseField>

<ResponseField name="--from <FROM>" type="number">
  Pagination offset (default: 0)
</ResponseField>

<ResponseField name="--scope <SCOPE>" type="string">
  Filter by organization scope
</ResponseField>

<ResponseField name="--registry <REGISTRY>" type="string">
  Registry URL
</ResponseField>

<ResponseField name="--format <FORMAT>" type="string">
  Output format (default: table). Possible values: table, json, yaml
</ResponseField>

<Accordion title="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
  ```
</Accordion>

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

<ResponseField name="--detailed" type="boolean">
  Show package details.
</ResponseField>

**`cache clear`**

Clear cache for a specific package, or all packages.

```bash theme={null}
npx codemod cache clear [PACKAGE] [--all]
```

<ResponseField name="[PACKAGE]" type="string">
  Package name (e.g., `@org/package` or `package`).
</ResponseField>

<ResponseField name="--all" type="boolean">
  Clear all cached packages.
</ResponseField>

**`cache prune`**

Prune old or unused cache entries.

```bash theme={null}
npx codemod cache prune [--max-age <MAX_AGE>] [--dry-run]
```

<ResponseField name="--max-age <MAX_AGE>" type="number">
  Maximum age in days to keep (default: 30).
</ResponseField>

<ResponseField name="--dry-run" type="boolean">
  Dry run - show what would be removed.
</ResponseField>