> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# nika:grep

> Usage, declared contract and source links for this Nika builtin.

[Builtins catalog](https://docs.nika.sh/reference/builtins.md) / `nika:grep`

> [card] File
>
> Tool family from the canonical registry.

> [card] [invoke](https://docs.nika.sh/reference/language/words/invoke.md)
>
> Call this builtin through the invoke verb.

## Read this contract

This reference preserves the specification at the revision linked below. Source examples are **fragments**: their surrounding tasks, inputs and permissions are not supplied here. Consult [engine status](https://docs.nika.sh/reference/status.md) and `nika catalog --tools --json` for the installed implementation; a registry declaration is not a runtime qualification.

## Usage and behavior

```yaml illustration theme={"system"}
invoke: { tool: "nika:grep", args: { pattern: "TODO:", path: "./src", case_insensitive: false } }
```

Recursive grep · returns array of `{ path, line, match }` · `line` is the
1-based line **number** (integer) · `match` the matched line text · results
sorted by `(path, line)`. `pattern:` is a **Rust-regex-class** expression
(RE2-compatible · no backreferences · the portable subset). Throws ·
`NIKA-BUILTIN-GREP-001` (invalid pattern · `validation_error`).

The read grants cover both the directory being walked and the files read
inside it. A literal directory grant does not grant its children. For the
recursive example above, declare the root and the descendant glob:

```yaml illustration theme={"system"}
permits:
  tools: ["nika:grep"]
  fs: { read: ["./src", "./src/**"] }
```

For one level of files, `./src/*` covers those files while `./src` still
covers the walk root. The root grant alone does not authorize their
contents; a file read outside the declared boundary is a permission
refusal, not evidence that the pattern has no matches.

***

## Related concepts

> [card] [Arguments](https://docs.nika.sh/reference/language/words/args.md)
>
> Pass the values required by the tool contract.

> [card] [Permissions](https://docs.nika.sh/concepts/security.md)
>
> Understand authority before granting effects.

> [card] [Errors and recovery](https://docs.nika.sh/reference/error-codes.md)
>
> Read diagnostics and choose a recovery policy.

> [card] [Workflow templates](https://docs.nika.sh/guides/templates.md)
>
> Put the fragment inside a complete workflow.

## Contract provenance

[Read the pinned specification](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/stdlib/builtins-v0.1.md#L284) · [Canonical registry](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/canon/builtins.yaml).

Tool identity: `nika:grep`. Specification revision: `5cd95cd25c0f`.

> [card] [Documentation](https://docs.nika.sh/introduction.md)
>
> Guides, reference contracts and working examples.

> [card] [Language spec](https://github.com/supernovae-st/nika-spec)
>
> the nine-key envelope, Apache-2.0. The contract these docs explain.

> [card] [Engine source](https://github.com/supernovae-st/nika)
>
> Rust, AGPL-3.0-or-later. Every commit public.

> [card] [TypeScript SDK](https://docs.nika.sh/sdk/overview.md)
>
> Use one typed lifecycle locally or against authenticated nika serve HTTP.

> [card] [Editor extension](https://marketplace.visualstudio.com/items?itemName=supernovae.nika)
>
> The editor extension, frozen at 0.120 and not qualified with 0.124: use `nika lsp` and the JSON Schema.

> [card] [Homebrew tap](https://github.com/supernovae-st/homebrew-tap)
>
> `brew install supernovae-st/tap/nika` for the latest tagged CLI release.

> [card] [SuperNovae](https://supernovae.studio)
>
> The Paris studio crafting Nika. 🦋


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.