# Use CLI Ast Grep

> Structural search and rewrite by AST pattern via ast-grep CLI.

- Skill: `thkt/use-cli-ast-grep` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thkt/use-cli-ast-grep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thkt/use-cli-ast-grep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thkt (https://skillmd.com/u/thkt)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/thkt/use-cli-ast-grep

---


# use-cli-ast-grep

## When to use

Structural queries and rewrites only. Route a match by AST shape to ast-grep, and keep text or regex matching on ugrep and bfs, and symbol-level call graphs on codegraph.

| Question                                                    | Tool        |
| ----------------------------------------------------------- | ----------- |
| Structural match / rewrite by AST pattern, syntax-tree unit | ast-grep    |
| Free-text, literal string, or regex search                  | ugrep / bfs |
| Symbol-level callers / callees, change impact               | codegraph   |
| Reading or editing one already-known location               | Read / Edit |

## Commands

`run` is a one-off search or rewrite, `scan` applies a rule file at scale, and `outline` extracts a symbol listing.

| Purpose                                    | Command                                                       |
| ------------------------------------------ | ------------------------------------------------------------- |
| Pattern search                             | `ast-grep run -p '<pattern>' -l <lang> <PATHS>`               |
| Pattern rewrite (with interactive confirm) | `ast-grep run -p '<pattern>' -r '<fix>' -l <lang> -i <PATHS>` |
| Pattern rewrite (apply all, no confirm)    | `ast-grep run -p '<pattern>' -r '<fix>' -l <lang> -U <PATHS>` |
| Rule-file scan / rewrite                   | `ast-grep scan -r <rule.yml> <PATHS>`                         |
| Symbol listing (structure overview)        | `ast-grep outline -l <lang> <PATHS>`                          |
| JSON output                                | `ast-grep run -p '<pattern>' --json <PATHS>`                  |

## Prerequisites

The call carries 3 required constraints.

| Item                      | Detail                                                                                                                                                                      |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| State PATHS explicitly    | `run` / `scan` / `outline` default PATHS to the whole current directory (`.`). Never omit it; state the target path on every call                                           |
| `-U` on a clean tree only | `-U` applies every rewrite without confirmation. Confirm a clean tree with `git status` before running it, and never run it on a dirty tree                                 |
| `.ja/` in the same pass   | When the target has a `.ja/` counterpart (see MIRROR.md), process both the `.ja/` side and the English side in the same session. Rewriting one side alone breaks the mirror |

## The help output is authoritative

Options, output format and exit codes live in `ast-grep --help` and `ast-grep <subcommand> --help`. Where help and memory differ, help is right.