Run Command

The run command executes a registered codemod from .codegen/codemods against a local repository.

graph-sitter run rename-function . --check

Usage

graph-sitter run LABEL [PATH] [OPTIONS]

PATH defaults to the active Graph-sitter session when omitted. Pass PATH explicitly for repeatable uvx and CI usage.

Arguments

• LABEL: The name of the codemod to run (e.g., "rename-function")
• PATH: Optional repository path to transform

Options

• --backend python|rust|auto: Choose the graph backend.
• --fallback python|error: Choose fallback behavior when the Rust backend is unavailable or unsupported for the requested API.
• --language auto|python|typescript: Choose the repository language.
• --subdir PATH: Limit parsing to a repository-relative subdirectory or file. Repeat to include multiple paths. This overrides any subdirectories declared by the registered codemod for this invocation.
• --arguments JSON: Pass arguments to the codemod as a JSON object. Typed Pydantic argument models are validated when present.
• --diff-preview N: Show the first N lines of the produced diff.
• --check: Run in a temporary copied repository, print the diff, leave the target unchanged, and exit non-zero when changes would be produced.
• --write: Apply changes to the target repository.

Examples

Preview a registered codemod:

graph-sitter run rename-function . --check

Apply a registered codemod:

graph-sitter run rename-function . --write

Run with arguments:

graph-sitter run rename-function . --arguments '{"old_name":"getUserData","new_name":"fetchUserProfile"}' --check

Run against only part of a large repository:

graph-sitter run rename-function ./airflow --subdir airflow/providers --subdir tests/providers --check

Run against a TypeScript repository:

graph-sitter run rename-component ./next.js --language typescript --backend auto --fallback python --check

With uvx

Published package form after release:

uvx --python 3.13 graph-sitter run rename-function . --arguments '{"old_name":"getUserData","new_name":"fetchUserProfile"}' --check
uvx --python 3.13 graph-sitter run rename-function ./airflow --subdir airflow/providers --check

Branch-built wheel validation form before release:

uvx --python 3.13 --from dist/<wheel>.whl graph-sitter run rename-function . --backend rust --fallback error --check

Safety Model

Use --check before --write for normal workflows. --check copies the target repository to a temporary Git repo before running the codemod, so codemods that call codebase.commit() internally do not mutate the original checkout.

For compatibility, run may still apply changes when neither --check nor --write is supplied. New docs, CI, and agent workflows should always pass an explicit mode.

Execution Flow

When you run a codemod, Graph-sitter:

1. Parses the selected repository into a code graph.
2. Resolves the registered codemod by LABEL.
3. Validates and passes --arguments when required.
4. Executes the codemod against the graph.
5. Prints a diff preview and either reports or applies the changes.