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

# Quickstart

> Create your first Codemod package and run it locally.

export const CLIDemo = () => {
  return <div style={{
    position: 'relative',
    paddingBottom: 'calc(62.5% + 41px)',
    height: 0,
    width: '100%'
  }}>
      <iframe src="https://demo.arcade.software/qpu8jeovSwfj5cDshEqp?embed&amp;embed_mobile=inline&amp;embed_desktop=inline&amp;show_copy_link=true" title="Codemod API Key Demo" frameBorder="0" loading="lazy" allowFullScreen allow="clipboard-write" style={{
    position: 'absolute',
    top: 0,
    left: 0,
    width: '100%',
    height: '100%',
    colorScheme: 'light'
  }} />
    </div>;
};

A **Codemod package** is a set of files that define an automated code transformation. Codemod Packages let you create, test, and distribute reusable transformations that update source code across entire codebases.

Packages range from quick, single-file refactors to advanced, multi-step migrations. They're fully portable—run them locally, in CI, or share with your team.

<Frame>
  <CLIDemo />
</Frame>

<Steps>
  <Step title="Create a new Codemod package">
    Scaffold a new Codemod package:

    ```bash theme={null}
    npx codemod init
    ```

    Each package includes your transformation logic (written in JavaScript, TypeScript, or YAML), a project manifest, and [workflow](/cli/packages/building-workflows) specification.

    When creating a new codemod project, you'll be prompted for:

    * **Project directory**
    * **Codemod type:**
      * <Tooltip tip="Best for simple code transformations. Uses the JavaScript ast-grep engine.">JavaScript ast-grep (jssg) codemod</Tooltip>
      * <Tooltip tip="Best for orchestrating large-scale migration campaigns. Combines shell commands, YAML ast-grep rules, and JS codemods into a single workflow.">Multi-step workflow (shell command, YAML & jssg)</Tooltip>
    * **Target language**
    * **Project name**
    * **Description**
    * **Author**
    * **License type**
    * **If your codemod is private**

    This creates a new folder with the required files and structure.
  </Step>

  <Step title="Explore the generated project">
    An example Codemod package:

    ```plaintext theme={null}
    example-codemod/
    ├── .gitignore
    ├── README.md
    ├── codemod.yaml        #  manifest and metadata
    ├── workflow.yaml       # Workflow definition for running the codemod
    ├── scripts/            # JS/TS codemods and shell scripts
    │   └── codemod.ts      # JS ast-grep codemod entry point
    └── rules/              # YAML ast-grep rule definitions
        └── config.yml
    ```

    <Info>
      You can combine different codemod types in a single package. The <code>scripts/</code> and <code>rules/</code> folders are conventional, not required—use any paths you prefer as long as you reference them correctly from <code>workflow\.yaml</code>.
    </Info>

    Check out the [Codemod package structure](/cli/packages/package-structure) for more details.
  </Step>

  <Step title="Understand an example workflow">
    The generated <code>workflow\.yaml</code> will differ depending on the codemod type you select:

    ```yaml Combined (jssg + yaml + shell + ai) theme={null}
    version: "1"
    nodes:
      - id: run-all
        name: Combined Example
        type: automatic
        steps:
          # 1) JS ast-grep (jssg)
          - name: "JS ast-grep codemod"
            js-ast-grep:
              js_file: "scripts/codemod.ts"
              base_path: "."
              language: "typescript"
              include:
                - "**/*.ts"
                - "**/*.tsx"

          # 2) YAML ast-grep
          - name: "Apply YAML ast-grep rules"
            ast-grep:
              config_file: "rules/config.yml"
              base_path: "./src"
              include:
                - "**/*.ts"
              exclude:
                - "**/*.test.ts"

          # 3) AI step
          - name: "AI review"
            ai:
              prompt: |
                Summarize risky changes and suggest tests.
          
          # 4) Shell command
          - name: "Format code"
            run: npx prettier --write "**/*.{ts,tsx,js,jsx}"

    ```

    Learn more about building workflows [here](/cli/packages/building-workflows).
  </Step>

  <Step title="Validate & run your Codemod package">
    ```bash theme={null}
    npx codemod workflow validate -w workflow.yaml
    npx codemod workflow run -w workflow.yaml
    ```

    This will check your workflow for errors and then run it locally.

    <Info>
      The <code>workflow validate</code> command checks syntax and schema compliance, but not logical correctness. Always test with real data to ensure expected behavior.
    </Info>
  </Step>
</Steps>