Content search

puck search is the repository's content search: a ripgrep-shaped verb over a linear-time, leftmost-longest regex engine with intersection, complement and lookaround. Use it in place of Grep, rg and grep for anything inside the checkout. Reach for the Glob tool only when the question is purely about path names: --files answers that inside the verb, over the same walk a search uses. Use symbol-analysis when the question is semantic rather than textual.

Start the CLI from a clean checkout

Run from the repository root with the checkout's own CLI build, never a published copy or the global puck tool, both of which lag the head. Copy src/Puck.Cli/bin/Release/net11.0/ to a scratch directory named for your lane and run the copy, so the running tool never locks the build output another build needs:

dotnet <lane>-cli/Puck.Cli.dll search <pattern> [path] [options]

If that build is absent, build it (dotnet build src/Puck.Cli -c Release -nodeReuse:false) and copy it (verification); dotnet run on the project runs the build in place and locks its output, so it is not a substitute for the copy.

If the copy cannot run, fall back to the host's literal or regex search. Say in the result that it came from a degraded fallback, keep the requested path, glob and case semantics, and never claim Puck-only intersection, complement or lookaround behavior for it. A "contains A but not B" condition still has to be checked: use a second filter or per-line inspection with the host tool.

Rules that prevent wrong answers

• Search paths are repository-relative unless the task says otherwise.
• Use -F for literal text; otherwise the pattern is the Puck regex dialect.
• Add -M 0 when all results are required; the default result cap is 250 and truncation is silent. -l lists files, -c counts matching lines per file, and -s matches across whole-file text and prints line ranges.
• Matching is case-sensitive by default. -i fixes the pattern and never the globs, and a stray case mismatch is the most common empty result.
• Globs are not ripgrep's. Brace sets and character classes are literal characters, and ** requires an intermediate directory, so src/Puck.Cli/**/*.cs silently misses src/Puck.Cli/Program.cs. Write -g "*.cs" for an extension and -g "src/**" for a subtree, repeating -g instead of writing {cs,md}.
• A pattern that starts with - needs -- before it, or it is parsed as a flag.
• Treat exit 0 as a match, 1 as no match, and 2 as an error. When a result surprises you, --files prints exactly which files the run would read.
• Text occurrences do not prove C# references, implementers, overrides, rename safety or deletion safety. Route those questions to symbol-analysis, whose verbs are puck references and puck declarations.
• Quote patterns for the active shell; do not silently rewrite regex syntax.
• The walk reads .puck DSL sources by default. The owner's ruling removes committed cartridge JSON twins: search the authored source and its imported modules. If the question concerns lowered defaults or expanded values, compile into a lane scratch directory and inspect that fresh output explicitly; ignored generated output is outside the default walk. An empty source search cannot establish that a generated value is absent.

Load the full reference selectively

Read references/complete-reference.md when you need exact flags, walk and glob behavior, engine semantics, syntax extensions, cookbook patterns (contains A but not B, files without a pattern, multiline blocks, whole-word alternations), shell escaping, or known limitations.

Related skills

Question	Skill
Who references, implements, overrides or can delete a C# symbol (puck references, puck declarations)	symbol-analysis
.puck name resolution and diagnostics	puck-dsl