Skip to content
Get packs

Guide · Open source

How to use ast-grep: search, rewrite and lint code

Updated · written with AI from the project's own documentation and checked against our catalogue data

ast-grep is a command-line tool that searches code by matching its abstract syntax tree instead of raw text. It is aimed at developers, library authors and tech leads who need more than plain text matching. After this guide you will know how to install it, write a simple pattern, rewrite matches and understand where YAML lint rules fit.

ast-grepast-grep/ast-grep · ★ 16.4k · MIT

Quick start

  1. 1Install the CLI. Choose a package manager such as npm, pip or Homebrew and run its install command for ast-grep.
  2. 2Check the install. Confirm the ast-grep command runs in your terminal before going further.
  3. 3Write a pattern. Write a pattern as ordinary code and use $ with uppercase letters as a wildcard for any single AST node.
  4. 4Set the language. Pass --lang or -l with the language of your files, such as ts.
  5. 5Run the search. Run ast-grep with --pattern or -p and review every match it returns.
  6. 6Rewrite matches. Add --rewrite or -r with a replacement pattern that reuses your wildcards, then review the changes.
  7. 7Add a YAML rule. Describe a repeatable check in YAML when you want to enforce the same practice across the project.

What does ast-grep do?

ast-grep is a CLI tool for code structural search, lint and rewriting. It works like grep, but it matches AST nodes instead of text. You write a pattern as if you were writing ordinary code, and ast-grep matches all code that has the same syntactical structure.

You can use a dollar sign followed by uppercase letters, such as $MATCH, as a wildcard that matches any single AST node. Unlike a regular expression dot, the wildcard is not textual.

  • Search code by structure rather than by exact text
  • Rewrite matches with a replacement pattern
  • Run lint rules defined in YAML

Install ast-grep with a package manager

ast-grep can be installed from npm, pip, cargo, cargo-binstall, Homebrew, scoop, mise or MacPorts. The README lists no prerequisites for the package-manager route. Pick the one you already use.

If you use pnpm, the README notes that running pnpm approve-builds may be needed after installing.

npm install --global @ast-grep/cli pip install ast-grep-cli brew install ast-grep cargo install ast-grep --locked

Run your first structural search

The basic form takes a pattern with a flag, a language with a flag, and optionally a rewrite. The short forms -p, -l and -r stand for pattern, language and rewrite in the README examples.

In the example below, $A matches any expression on the left and on the right of the logical and, so the search finds every place that calls a value after a check, whatever the names are.

  • --pattern (-p): the code structure to search for
  • --lang (-l): the language to parse, for example ts
  • --rewrite (-r): the replacement code, used for rewriting
ast-grep -p '$A && $A()' -l ts -r '$A?.()'

Rewrite code across a codebase

Rewriting uses the same pattern syntax. The rewrite pattern reuses the wildcards captured in the search pattern. The README gives an example that migrates code to the null coalescing style.

The -i flag appears in one of the README examples, which is used to migrate a library call by removing a trailing as const. Check the flag's behaviour with the tool's own help before running it on a large codebase.

  • Start with a narrow search and review the matches before applying a rewrite
  • Use the same language flag across the search and rewrite
ast-grep -p 'new Zodios($URL, $CONF as const,)' -l ts -r 'new Zodios($URL, $CONF)' -i

Write lint rules in YAML

ast-grep supports YAML configuration to write new linting rules or code modifications. The README includes an example of implementing an eslint-style rule using YAML, and links to the author's write-up for it.

Rules are useful when a team wants to enforce code practices that fit its own needs. The README describes this use for tech leads.

  • Define a rule once in YAML and reuse it across the project
  • Use rules to enforce team practices that generic linters do not cover

Build from source if you need to

If none of the package managers suit you, the README says you can build ast-grep from source. You need to install rustup first, then clone the repository and run the command below.

The README also says packages are available on other platforms through Repology.

cargo install --path ./crates/cli --locked

What people use it for

  • Find every usage of a function or API across a codebase, including all the places with the same shape.
  • Migrate users of a library across a breaking API change, as library authors can do with ast-grep.
  • Rewrite a pattern consistently across many files, such as moving code to a newer syntax.
  • Enforce custom team coding practices with YAML lint rules.
  • Write rules for lightweight static analysis, as the README suggests for security research.

Frequently asked questions

Is ast-grep free to use?

ast-grep is released under the MIT licence, as listed on its repository page. You can use it, including in commercial work, under the terms of that licence.

How do I install ast-grep?

The README lists install commands for npm, pip, Homebrew and cargo. For example, you can run npm install --global @ast-grep/cli or brew install ast-grep. Other options include scoop, mise and MacPorts.

What are the requirements for ast-grep?

The source does not list prerequisites for the package-manager install. Building from source requires rustup, a clone of the repository and the cargo command shown in the README.

Is ast-grep the same as grep?

No. grep matches text, while ast-grep matches AST nodes, so a pattern written like ordinary code can find code with the same structure. For simple text searches, plain grep or ripgrep is simpler.

How does ast-grep compare to Semgrep or jscodeshift?

The README lists Semgrep, comby, ripgrep and jscodeshift as comparable projects but does not compare them in detail. Check each project's documentation to choose between them for your task.

Which languages does ast-grep support?

ast-grep is built on tree-sitter based parsing, and you pass the language with --lang. The README does not fully list supported languages, so check the project website or playground before relying on one.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ast-grep suits developers who want grep-style search that understands code structure, and teams that need to migrate APIs or enforce custom rules. If you only need plain text search, use grep or ripgrep, and if you are not comfortable with code syntax, the patterns will be hard to write.

Install options & downloads