# search

> Find under a folder by name fragment, by content term, or by both

*Reads only.*

Find under a folder by name fragment, by content term, or by both.

Expects nothing and changes nothing. name matches a fragment of a name anywhere beneath
the folder; text matches a word inside a text file's content. At least one of the two is
required, and both together narrow to items matching both. Results carry the same fields
a listing does, so a revision may be read from them.

This answers one page at a time and carries a cursor when there is more, null when that
was the whole of it. Pass the cursor back as cursor until it comes back null: a page is
not the whole folder, so never conclude from one page that something is not there.

## Arguments

| Argument | Type | Required | Meaning |
| --- | --- | --- | --- |
| `folder_id` | text | yes | The folder to search under |
| `name` | text | no | A fragment of the name to look for |
| `text` | text | no | A term to look for inside text files |
| `limit` | count | no | How many items this page may hold |
| `cursor` | text | no | Continue from the cursor a previous page reported |

## On the command line

```sh
flie agent search FOLDER_ID [--name TEXT] [--text TERM] [--limit N] [--cursor C]
```

```sh
flie --json agent search FOLDER_ID --name draft [--limit N] [--cursor C]   # by name fragment
flie --json agent search FOLDER_ID --text "hypothesis"  # by a word in a text file's content
```
