ast-grep-cli

What it is and what it does

ast-grep-cli is a structural code search and rewrite tool built on tree-sitter parsing. Instead of matching text patterns like grep, it matches abstract syntax tree nodes, letting you write patterns as ordinary code with wildcards (like `$MATCH`) to find and replace code with identical syntactical structure across a codebase.

The tool is written in Rust for performance and supports multiple languages. It's designed for large-scale code manipulation tasks: library authors can use it to help users adopt breaking changes, teams can enforce code best practices, and security researchers can write detection rules. It can be driven from the command line with pattern and rewrite flags, or configured via YAML for custom linting rules.

Use it for:

• Migrate code to use null coalescing operators or other modern syntax patterns across a large TypeScript codebase.
• Enforce team code standards by writing AST-based linting rules in YAML without writing custom ESLint plugins.
• Perform large-scale library API migrations by defining structural patterns that match the old API and rewrite them to the new one.
• Detect security anti-patterns or code smells by searching for specific AST structures across multiple files and languages.
• Refactor code idiomatically (e.g., replace callback patterns with async/await) by matching syntactic structure rather than text.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ast-grep-cli is a command-line tool for searching, linting, and rewriting code using abstract syntax tree patterns instead of text matching.

Yes, if you need to search or refactor code at scale using syntax-aware patterns. The tool is actively maintained, has no known vulnerabilities, and solves a real problem that text-based grep cannot. Medium install friction (compiled binary) is typical for performance-critical tools. Verify Python version support before committing to a project dependency.

Install

ast-grep-cli on PyPI

pip install ast-grep-cli

uv add ast-grep-cli

poetry add ast-grep-cli

Installing ast-grep-cli

Before you install

Medium install friction due to platform-specific wheels (compiled Rust binary). Actively maintained with recent releases; last commit 2026-08-14 and 15516 repository stars indicate solid ongoing support.

License in practice

MIT license (permissive) means you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart

pip install ast-grep-cli

ast-grep --pattern 'var code = $PATTERN' --rewrite 'let code = new $PATTERN' --lang ts

Requires a supported language (ts, js, python, etc.) to be specified via --lang flag; pattern syntax must match valid code structure for the target language.

Verify before relying

• Whether the Python package wraps the compiled Rust binary or requires separate installation of the Rust tool.
• What Python versions are officially supported (requires_python is unspecified in metadata).
• Performance characteristics and scalability limits for very large codebases.

Package facts

Evidence: ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl; ast_grep_cli-0.45.1-py3-none-macosx_10_12_x86_64.whl; ast_grep_cli-0.45.1-py3-none-manylinux_2_28_aarch64.whl; ast_grep_cli-0.45.1-py3-none-manylinux_2_28_x86_64.whl; ast_grep_cli-0.45.1-py3-none-win32.whl; ast_grep_cli-0.45.1-py3-none-win_amd64.whl; ast_grep_cli-0.45.1-py3-none-win_arm64.whl

Keywords: ast, pattern, codemod, structural search, rewrite

Tags

More Software Development packages