ast-grep CLI

CuratedAudited 2026-10-28 by anc 0.7.0Markdown · JSON
75pass rate

3/8 principles met

Structural search and replace for code using AST patterns

$ anc audit sg --json

workhorse Rust ast-grep/ast-grep
MUST 19 / 28SHOULD 14 / 221 failing12 warningsaudited 2026-10-28 · anc 0.7.0

Eight principles, scored

Behavioral and source checks. Every non-pass row carries a copy-paste remediation prompt.

  1. P1
    Non-Interactive by Default

    4 flag(s) found in --help but no `[env: NAME]` bindings advertised · no rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.

    Remediation · P1
    Make ast-grep satisfy P1 (Non-Interactive by Default) from the agent-native CLI standard. Address:
    - Flags advertise env-var bindings in --help (4 flag(s) found in --help but no `[env: NAME]` bindings advertised)
    - Rich-TUI affordance for TTY contexts (no rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.)
    Requirements: https://anc.dev/p1
    warn
  2. P2
    Structured, Parseable Output

    no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum. · no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.

    Remediation · P2
    Make ast-grep satisfy P2 (Structured, Parseable Output) from the agent-native CLI standard. Address:
    - --json / --jsonl short aliases for --output (no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.)
    - `--raw` flag for pipe-safe unformatted output (no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.)
    Requirements: https://anc.dev/p2
    warn
  3. P3
    Progressive Help Discovery

    no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text. · subcommands missing example invocations in their `--help`: run, scan, test, new, outline. Examples teach agents the call shape faster than option tables; use clap's `after_help` or a dedicated `Examples:` block. exempt: lsp (take no arguments).

    Remediation · P3
    Make ast-grep satisfy P3 (Progressive Help Discovery) from the agent-native CLI standard. Address:
    - `examples` subcommand or `--examples` flag for curated usage patterns (no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.)
    - Each subcommand that takes arguments ships an invocation example in its `--help` (subcommands missing example invocations in their `--help`: run, scan, test, new, outline. Examples teach agents the call shape faster than option tables; use clap's `after_help` or a dedicated `Examples:` block. exempt: lsp (take no arguments).)
    - Help text pairs human and `--output json` example invocations (no paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.)
    Requirements: https://anc.dev/p3
    fail
  4. P4pass
  5. P5pass
  6. P6
    Composable, Predictable Command Structure

    4/8 subcommand(s) follow standard verb names. Non-standard: scan, new, lsp, outline. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs. · no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.

    Remediation · P6
    Make ast-grep satisfy P6 (Composable, Predictable Command Structure) from the agent-native CLI standard. Address:
    - Subcommand verbs follow community-standard names (4/8 subcommand(s) follow standard verb names. Non-standard: scan, new, lsp, outline. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs.)
    - `--color` flag for explicit color control (no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.)
    Requirements: https://anc.dev/p6
    warn
  7. P7
    Bounded, High-Signal Responses

    no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count. · no `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.

    Remediation · P7
    Make ast-grep satisfy P7 (Bounded, High-Signal Responses) from the agent-native CLI standard. Address:
    - Quiet mode available (no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.)
    - `--verbose` flag for diagnostic escalation (no `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.)
    - `--timeout` flag for long-running operations (no long-running subcommand advertises a timeout flag in its --help: run (looked for --timeout, --deadline, --max-time). SHOULD-tier: without a bound, agents that hit a hung operation have to enforce timeouts externally.)
    - Help text advertises TTY-aware verbosity behavior (no TTY-aware language found in `--help`. MAY-tier — automatic verbosity reduction when stdout is piped or redirected lets agents skip the explicit `--quiet` flag. Behavioral probes cannot simulate a real TTY without a pty crate, so this audit relies on documented intent.)
    Requirements: https://anc.dev/p7
    warn
  8. P8pass

All Audits

P1: Non-Interactive by Default

PASSNon-interactive by default
SKIPNon-interactive gate flag advertised in --helptarget satisfies P1 via alternative gate (help-on-bare or stdin-primary)
WARNFlags advertise env-var bindings in --help4 flag(s) found in --help but no `[env: NAME]` bindings advertised
PASSSecret-bearing flags expose stdin or *-file companion
PASS`--help` advertises default values for flags
WARNRich-TUI affordance for TTY contextsno rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.

P2: Structured, Parseable Output

SKIPStructured output support`--format` is declared in `scan --help`, but no safe probe printed JSON (--help and --version override output flags in most CLIs)
SKIPStructured-output CLI exposes its schema at runtimeantecedent `p2-json-output` could not be measured: `--format` is declared in `scan --help`, but no safe probe printed JSON (--help and --version override output flags in most CLIs)
WARN--json / --jsonl short aliases for --outputno --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.
WARN`--raw` flag for pipe-safe unformatted outputno `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.
SKIP`--output` advertises additional formats beyond text/jsonno `--output` or `--format` flag advertised; vacuous skip for MAY-tier extra formats.
PASSBad invocation exits with structured usage-error code (2)
SKIPErrors emit JSON envelope with discriminant + type id + message roles under `--output json`no option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); MUST applies only to CLIs that opt into the JSON contract.
SKIPJSON success and error envelopes share their non-payload key setno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); envelope-consistency only applies to CLIs that opt into the JSON contract.

P3: Progressive Help Discovery

PASSHelp flag produces useful output
PASSVersion flag works (`--version` plus short alias)
PASSVersion flag works (`--version` plus short alias)
WARN`examples` subcommand or `--examples` flag for curated usage patternsno `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.
PASSShort `-h` summary differs from `--help` long form
FAILEach subcommand that takes arguments ships an invocation example in its `--help`subcommands missing example invocations in their `--help`: run, scan, test, new, outline. Examples teach agents the call shape faster than option tables; use clap's `after_help` or a dedicated `Examples:` block. exempt: lsp (take no arguments).
WARNHelp text pairs human and `--output json` example invocationsno paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.
PASSCommand-list entries name the command without repeating the binary name

P4: Fail-Fast, Actionable Errors

PASSRejects invalid arguments
PASSError messages include a hint or remediation phrase
SKIP`--output json` produces JSON-formatted errorsno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); SHOULD applies only to CLIs that opt into the JSON contract.

P5: Safe Retries & Mutation Boundaries

SKIPDestructive subcommands require `--force` or `--yes`no destructive subcommands detected; MUST applies conditionally to CLIs with destructive operations.
SKIPRead and write surfaces are both visible in subcommand listno recognizable read or write subcommand verbs; the read/write distinction is unobservable from the help surface alone.

P6: Composable, Predictable Command Structure

PASSHandles SIGPIPE gracefully
SKIPPager-using CLI ships --no-pager escape hatchno pager signal ($PAGER, --pager, pager, or less/more named as a program) in --help
PASSRespects NO_COLOR
WARNSubcommand verbs follow community-standard names4/8 subcommand(s) follow standard verb names. Non-standard: scan, new, lsp, outline. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs.
WARN`--color` flag for explicit color controlno `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.
SKIPInput-accepting commands read from stdin when no file is givenno input-accepting subcommand detected (process/parse/convert/transform/analyze/validate/format/lint/audit); vacuous skip for the conditional SHOULD.
PASSSubcommand naming follows a consistent verb/noun convention
PASSOperations are subcommands, not verb-shaped flags

P7: Bounded, High-Signal Responses

WARNQuiet mode availableno option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.
WARN`--verbose` flag for diagnostic escalationno `--verbose` / `-v` flag advertised. SHOULD-tier — agents debugging failures need a way to escalate diagnostic detail.
SKIP`--limit` / `--max-results` flag for list operationsno list-style subcommand detected (list/ls/search/query/find, or a show/get whose summary describes several results); vacuous skip for the list-only SHOULD.
SKIPCursor-based pagination flags for list traversalno list-style subcommand detected (list/ls/search/query/find, or a show/get whose summary describes several results); vacuous skip for the list-only MAY.
WARN`--timeout` flag for long-running operationsno long-running subcommand advertises a timeout flag in its --help: run (looked for --timeout, --deadline, --max-time). SHOULD-tier: without a bound, agents that hit a hung operation have to enforce timeouts externally.
WARNHelp text advertises TTY-aware verbosity behaviorno TTY-aware language found in `--help`. MAY-tier — automatic verbosity reduction when stdout is piped or redirected lets agents skip the explicit `--quiet` flag. Behavioral probes cannot simulate a real TTY without a pty crate, so this audit relies on documented intent.

P8: Discoverable Through Agent Skill Bundles

N/ASkill bundle has install path (`tool skill install [<host>]`)no skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill install --all` for multi-runtime installno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill update` / `skill upgrade` for bundle refreshno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand

Details

Version scored
0.51.0
Audit date
2026-10-28 15:52:56 UTC
Duration
179ms
Platform
linux/x86_64
Mode
command
Anc build
0.7.0
Install
brew install ast-grep

Embed the badge

This score (75%) clears the badge floor (70%). Copy this into your README:

[![agent-native](https://anc.dev/badge/sg.svg)](https://anc.dev/score/sg)

Preview: agent-native badge for ast-grep

Reproduce this scorecard for ast-grep locally and inspect the failing audits:

anc audit --command sg --output json

Install anc first if you don't have it. Add --output json to get the same JSON shape committed under scorecards/.