---
id: ast-grep-cli
version: "0.45.1"
license: unclear
license_treatment: permissive
maintenance: active
---

# ast-grep-cli — Structural Search and Rewrite code at large scale using precise AST pattern.

License: permissive · Maintenance: active · Downloads: 2.8M/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: unspecified
- Install friction: medium
- Maintenance: active
- Downloads: 2.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ast pattern matching code search, structural code search and rewrite, codemod tool ast-based, code linting with ast patterns, tree-sitter pattern matching, large-scale code refactoring, syntax tree code analysis, codemod, ast-based-search, refactoring

[View on SkillFed](https://skillfed.io/packages/ast-grep-cli) · [View on PyPI](https://pypi.org/project/ast-grep-cli/)