Skip to content

docs(search): trim output with --json=<fields>, as measured #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leemour merged 1 commit into from
Oct 15, 2026
Merged

docs(search): trim output with --json=<fields>, as measured #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions content/docs/search-efficiently.es.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,9 @@ La respuesta indica si hay más resultados (`has_more`). Eso describe la página
## Mantén la salida corta

- `--limit <n>` limita los resultados.
- `--brief` muestra cada mensaje encontrado como referencia, hora, remitente y extracto. Revisa con él y luego abre un resultado.
- `--json=ref` conserva solo los campos que nombras. `--jsonl` imprime un resultado por línea. `--full` devuelve los textos completos.
- `--json=<campos>` conserva solo los campos que nombras, por ejemplo `--json=ref,date,text`. Es la única opción
que reduce cualquier respuesta: entre un 31% y un 64% menos que `--json` completo en [nuestra medición](https://github.com/WireCatLabs/cli-testing/tree/main/performance/agents/output-size).
- `--jsonl` imprime un resultado por línea. No es más corto que `--json`. `--full` devuelve los textos completos.
- `--max-output-bytes` limita por defecto la salida automática a 4 MiB. Un resultado que supera el límite falla de forma visible en lugar de recortarse.
- `--context <n>` añade `n` mensajes vecinos a cada lado de un resultado. Vale 0 cuando la salida no es un terminal.

Expand All @@ -114,8 +115,8 @@ Sustituye los nombres por los tuyos.
| --- | --- |
| Un acuerdo y su fuente | `tg personal search messages 'chat:"Book club" agreed date>=2026-10-01' --limit 5` |
| Todo sobre una persona este mes | `tg personal contacts timeline "Kai Sample" --since-time 2026-10-01` |
| Dónde aparece un número de teléfono | `tg personal search messages 'phone:"+1 555 010 0100"' --brief` |
| Archivos enviados a un chat la semana pasada | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07' --brief` |
| Dónde aparece un número de teléfono | `tg personal search messages 'phone:"+1 555 010 0100"'` |
| Archivos enviados a un chat la semana pasada | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07'` |
| Qué dice un documento de Drive sobre un tema | `drive personal search 'budget' --exact --limit 5` |

Para recetas más largas: [Telegram](./tg/recipes.md) y [MAX](./max/recipes.md).
Expand Down
9 changes: 5 additions & 4 deletions content/docs/search-efficiently.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,9 @@ The answer says whether more results exist (`has_more`). That describes the page
## Keep the output small

- `--limit <n>` caps the hits.
- `--brief` shows each found message as a reference, time, sender and excerpt. Scan with it, then open one hit.
- `--json=ref` keeps only the fields you name. `--jsonl` prints one result per line. `--full` returns whole texts.
- `--json=<fields>` keeps only the fields you name, for example `--json=ref,date,text`. It is the one option that
shrinks every answer: 31% to 64% smaller than full `--json` in [our measurement](https://github.com/WireCatLabs/cli-testing/tree/main/performance/agents/output-size).
- `--jsonl` prints one result per line. It is no smaller than `--json`. `--full` returns whole texts.
- `--max-output-bytes` caps machine output at 4 MiB by default. A result over the cap fails visibly instead of being cut.
- `--context <n>` adds `n` neighbouring messages on each side of a hit. It is 0 when the output is not a terminal.

Expand All @@ -114,8 +115,8 @@ Replace the names with yours.
| --- | --- |
| An agreement and its source | `tg personal search messages 'chat:"Book club" agreed date>=2026-10-01' --limit 5` |
| Everything about one person this month | `tg personal contacts timeline "Kai Sample" --since-time 2026-10-01` |
| Where a phone number appears | `tg personal search messages 'phone:"+1 555 010 0100"' --brief` |
| Files sent in a chat last week | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07' --brief` |
| Where a phone number appears | `tg personal search messages 'phone:"+1 555 010 0100"'` |
| Files sent in a chat last week | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07'` |
| What a Drive document says about a topic | `drive personal search 'budget' --exact --limit 5` |

For longer ones, see the recipes for [Telegram](./tg/recipes.md) and [MAX](./max/recipes.md).
Expand Down
9 changes: 5 additions & 4 deletions content/docs/search-efficiently.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,9 @@ tg personal search messages 'chat:"Book club" from:"Kai Sample" date>=2026-10-01
## Держите вывод коротким

- `--limit <n>` ограничивает число результатов.
- `--brief` показывает каждое найденное сообщение как ссылку на источник, время, отправителя и фрагмент. Просмотрите так, потом откройте один результат.
- `--json=ref` оставляет только названные поля. `--jsonl` печатает по одному результату в строке. `--full` возвращает тексты целиком.
- `--json=<поля>` оставляет только названные поля, например `--json=ref,date,text`. Только этот флаг уменьшает
любой ответ: на 31–64% меньше полного `--json` в [нашем замере](https://github.com/WireCatLabs/cli-testing/tree/main/performance/agents/output-size).
- `--jsonl` печатает по одному результату в строке. Он не короче `--json`. `--full` возвращает тексты целиком.
- `--max-output-bytes` по умолчанию ограничивает машинный вывод 4 МиБ. Результат больше лимита завершается явной ошибкой, а не обрезается.
- `--context <n>` добавляет `n` соседних сообщений с каждой стороны. Вне терминала значение равно 0.

Expand All @@ -114,8 +115,8 @@ tg personal messages context "msg:telegram/1/77/42" --thread
| --- | --- |
| Договорённость и её источник | `tg personal search messages 'chat:"Book club" agreed date>=2026-10-01' --limit 5` |
| Всё об одном человеке за этот месяц | `tg personal contacts timeline "Kai Sample" --since-time 2026-10-01` |
| Где встречается номер телефона | `tg personal search messages 'phone:"+1 555 010 0100"' --brief` |
| Файлы, присланные в чат на прошлой неделе | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07' --brief` |
| Где встречается номер телефона | `tg personal search messages 'phone:"+1 555 010 0100"'` |
| Файлы, присланные в чат на прошлой неделе | `tg personal search messages 'chat:"Book club" has:file date>=2026-10-07'` |
| Что документ Drive говорит о теме | `drive personal search 'budget' --exact --limit 5` |

Более длинные примеры: [Telegram](./tg/recipes.md) и [MAX](./max/recipes.md).
Expand Down
Loading